@messagevisor/core 0.0.1 → 0.1.0

package/src/index.ts

@@ -0,0 +1,18 @@
+export * from "./builder";
+export * from "./benchmark";
+export * from "./cli";
+export * from "./config";
+export * from "./create";
+export * from "./datasource";
+export * from "./examples";
+export * from "./prune";
+export * from "./evaluate";
+export * from "./exporter";
+export * from "./find-duplicates";
+export * from "./generate-code";
+export * from "./info";
+export * from "./importer";
+export * from "./init";
+export * from "./linter";
+export * from "./promoter";
+export * from "./tester";

package/src/info/index.ts

@@ -0,0 +1,67 @@
+import type { Datasource } from "../datasource";
+import { assertProjectSetJsonSelection, getProjectSetExecutions } from "../sets";
+
+export async function getProjectInfo(datasource: Datasource) {
+  const [locales, messages, segments, attributes, targets, tests] = await Promise.all([
+    datasource.listLocales(),
+    datasource.listMessages(),
+    datasource.listSegments(),
+    datasource.listAttributes(),
+    datasource.listTargets(),
+    datasource.listTests(),
+  ]);
+
+  return {
+    locales: locales.length,
+    messages: messages.length,
+    segments: segments.length,
+    attributes: attributes.length,
+    targets: targets.length,
+    tests: tests.length,
+  };
+}
+
+export const infoPlugin = {
+  command: "info",
+  handler: async ({ datasource, parsed }: any) => {
+    const projectConfig = datasource.getConfig();
+    assertProjectSetJsonSelection(projectConfig, parsed.set, parsed.json);
+
+    if (projectConfig.sets) {
+      const executions = await getProjectSetExecutions(projectConfig, datasource, parsed.set);
+      const infoBySet: Record<string, Awaited<ReturnType<typeof getProjectInfo>>> = {};
+
+      for (const execution of executions) {
+        infoBySet[execution.set] = await getProjectInfo(execution.datasource);
+      }
+
+      if (parsed.json) {
+        console.log(parsed.pretty ? JSON.stringify(infoBySet, null, 2) : JSON.stringify(infoBySet));
+        return;
+      }
+
+      console.log("\nProject info:\n");
+      for (const set of Object.keys(infoBySet)) {
+        console.log(`Set "${set}":`);
+        for (const key of Object.keys(infoBySet[set])) {
+          console.log(`  - ${key}: ${(infoBySet[set] as any)[key]}`);
+        }
+        console.log("");
+      }
+      return;
+    }
+
+    const info = await getProjectInfo(datasource);
+
+    if (parsed.json) {
+      console.log(parsed.pretty ? JSON.stringify(info, null, 2) : JSON.stringify(info));
+      return;
+    }
+
+    console.log("\nProject info:\n");
+    for (const key of Object.keys(info)) {
+      console.log(`  - ${key}: ${(info as any)[key]}`);
+    }
+  },
+  examples: [{ command: "info", description: "show project entity counts" }],
+};

package/src/init/index.spec.ts

@@ -0,0 +1,279 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { Datasource } from "../datasource";
+import { getProjectConfig } from "../config";
+import { lintProject } from "../linter";
+import { DEFAULT_PROJECT, initProject, initProjectFromCLI } from "./index";
+
+const tar: any = require("tar");
+
+const REPO_ROOT = path.resolve(__dirname, "../../../..");
+const PROJECT_FIXTURES = [
+  "projects/project-yml",
+  "projects/project-json",
+  "projects/project-raw",
+  "projects/project-environments",
+  "projects/project-test-envs",
+];
+
+let tarballPathPromise: Promise<string> | undefined;
+
+async function getFixtureTarballPath() {
+  if (!tarballPathPromise) {
+    tarballPathPromise = (async () => {
+      const tempDirectoryPath = await fs.promises.mkdtemp(
+        path.join(os.tmpdir(), "messagevisor-init-tarball-"),
+      );
+      const tarballPath = path.join(tempDirectoryPath, "examples.tar.gz");
+
+      await tar.c(
+        {
+          gzip: true,
+          file: tarballPath,
+          cwd: REPO_ROOT,
+          prefix: "messagevisor-main/",
+        },
+        PROJECT_FIXTURES,
+      );
+
+      return tarballPath;
+    })();
+  }
+
+  return tarballPathPromise;
+}
+
+async function createDestinationDirectory() {
+  return fs.promises.mkdtemp(path.join(os.tmpdir(), "messagevisor-init-destination-"));
+}
+
+async function installModuleIcuStub(directoryPath: string) {
+  const moduleDirectoryPath = path.join(
+    directoryPath,
+    "node_modules",
+    "@messagevisor",
+    "module-icu",
+  );
+
+  await fs.promises.mkdir(moduleDirectoryPath, { recursive: true });
+  await fs.promises.writeFile(
+    path.join(moduleDirectoryPath, "index.js"),
+    "exports.createICUModule = function () { return { name: 'icu' }; };\n",
+  );
+}
+
+describe("initProject", function () {
+  it("defaults to the yml starter and strips generated artifacts", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+
+    const result = await initProject(directoryPath, DEFAULT_PROJECT, {
+      tarballPath,
+    });
+
+    expect(result.project).toEqual("yml");
+    expect(fs.existsSync(path.join(directoryPath, "messagevisor.config.js"))).toBe(true);
+    expect(fs.existsSync(path.join(directoryPath, "messages/nav/contact.yml"))).toBe(true);
+    expect(fs.existsSync(path.join(directoryPath, "tests/messages/nav/contact.spec.yml"))).toBe(
+      true,
+    );
+    expect(fs.existsSync(path.join(directoryPath, "datafiles"))).toBe(false);
+    expect(fs.existsSync(path.join(directoryPath, ".messagevisor", "REVISION"))).toBe(false);
+
+    await installModuleIcuStub(directoryPath);
+    const projectConfig = getProjectConfig(directoryPath);
+    const datasource = new Datasource(projectConfig, directoryPath);
+    const lintResult = await lintProject(projectConfig, datasource);
+    expect(lintResult.hasError).toBe(false);
+  });
+
+  it("scaffolds the json starter", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+
+    await initProject(directoryPath, "json", { tarballPath });
+
+    expect(fs.existsSync(path.join(directoryPath, "locales/en.json"))).toBe(true);
+    expect(fs.existsSync(path.join(directoryPath, "tests/messages/nav/contact.spec.json"))).toBe(
+      true,
+    );
+    expect(fs.existsSync(path.join(directoryPath, "messagevisor.config.js"))).toBe(true);
+  });
+
+  it("scaffolds the environments starter with sets and strips generated artifacts", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+
+    await initProject(directoryPath, "environments", { tarballPath });
+
+    expect(fs.existsSync(path.join(directoryPath, "sets/dev/messages/nav/contact.yml"))).toBe(true);
+    expect(fs.existsSync(path.join(directoryPath, "sets/staging/tests/targets/web.spec.yml"))).toBe(
+      true,
+    );
+    expect(fs.existsSync(path.join(directoryPath, "datafiles"))).toBe(false);
+    expect(
+      fs.existsSync(path.join(directoryPath, ".messagevisor", "sets", "dev", "REVISION")),
+    ).toBe(false);
+  });
+
+  it("fails clearly for unknown projects", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+
+    await expect(
+      initProject(directoryPath, "nope", {
+        tarballPath,
+      }),
+    ).rejects.toThrow(
+      'Unknown project "nope". No matching project-nope found in examples tarball.',
+    );
+  });
+
+  it("fails in a non-empty destination without overwrite", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+    await fs.promises.writeFile(path.join(directoryPath, "existing.txt"), "hello");
+
+    await expect(
+      initProject(directoryPath, "yml", {
+        tarballPath,
+      }),
+    ).rejects.toThrow("Pass --overwrite to initialize there and skip conflicting files.");
+  });
+
+  it("skips conflicting files when overwrite is enabled", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+    const configPath = path.join(directoryPath, "messagevisor.config.js");
+    await fs.promises.writeFile(configPath, "module.exports = { custom: true };\n");
+
+    const result = await initProject(directoryPath, "yml", {
+      tarballPath,
+      overwrite: true,
+    });
+
+    expect(result.skippedConflictCount).toBeGreaterThanOrEqual(1);
+    expect(await fs.promises.readFile(configPath, "utf8")).toEqual(
+      "module.exports = { custom: true };\n",
+    );
+    expect(fs.existsSync(path.join(directoryPath, "locales/en.yml"))).toBe(true);
+  });
+});
+
+describe("initProjectFromCLI", function () {
+  it("initializes in place when the current directory is empty without prompting", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+    const promptDirectoryName = jest.fn();
+
+    const result = await initProjectFromCLI(directoryPath, DEFAULT_PROJECT, {
+      tarballPath,
+      promptDirectoryName,
+    });
+
+    expect(result.destinationDirectoryPath).toEqual(directoryPath);
+    expect(promptDirectoryName).not.toHaveBeenCalled();
+    expect(fs.existsSync(path.join(directoryPath, "messagevisor.config.js"))).toBe(true);
+  });
+
+  it("prompts for a child directory when the current directory is not empty", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+    await fs.promises.writeFile(path.join(directoryPath, "existing.txt"), "hello");
+
+    const result = await initProjectFromCLI(directoryPath, DEFAULT_PROJECT, {
+      tarballPath,
+      promptDirectoryName: async () => "my-project",
+    });
+    const projectDirectoryPath = path.join(directoryPath, "my-project");
+
+    expect(result.destinationDirectoryPath).toEqual(projectDirectoryPath);
+    expect(fs.existsSync(path.join(directoryPath, "existing.txt"))).toBe(true);
+    expect(fs.existsSync(path.join(projectDirectoryPath, "messagevisor.config.js"))).toBe(true);
+  });
+
+  it("rejects a blank prompted directory name", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+    await fs.promises.writeFile(path.join(directoryPath, "existing.txt"), "hello");
+
+    await expect(
+      initProjectFromCLI(directoryPath, DEFAULT_PROJECT, {
+        tarballPath,
+        promptDirectoryName: async () => "   ",
+      }),
+    ).rejects.toThrow("Directory name is required to initialize a new Messagevisor project.");
+  });
+
+  it("rejects absolute and nested prompted directory names", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+    await fs.promises.writeFile(path.join(directoryPath, "existing.txt"), "hello");
+
+    await expect(
+      initProjectFromCLI(directoryPath, DEFAULT_PROJECT, {
+        tarballPath,
+        promptDirectoryName: async () => path.join(directoryPath, "project"),
+      }),
+    ).rejects.toThrow("Directory name must be a simple folder name");
+
+    await expect(
+      initProjectFromCLI(directoryPath, DEFAULT_PROJECT, {
+        tarballPath,
+        promptDirectoryName: async () => "nested/project",
+      }),
+    ).rejects.toThrow("Directory name must be a simple folder name");
+  });
+
+  it("rejects an existing non-empty child directory", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+    const childDirectoryPath = path.join(directoryPath, "my-project");
+    await fs.promises.writeFile(path.join(directoryPath, "existing.txt"), "hello");
+    await fs.promises.mkdir(childDirectoryPath);
+    await fs.promises.writeFile(path.join(childDirectoryPath, "existing.txt"), "hello");
+
+    await expect(
+      initProjectFromCLI(directoryPath, DEFAULT_PROJECT, {
+        tarballPath,
+        promptDirectoryName: async () => "my-project",
+      }),
+    ).rejects.toThrow("Please choose a different directory name.");
+  });
+
+  it("initializes in the current directory without prompting when overwrite is enabled", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+    const promptDirectoryName = jest.fn();
+    await fs.promises.writeFile(path.join(directoryPath, "existing.txt"), "hello");
+
+    const result = await initProjectFromCLI(directoryPath, DEFAULT_PROJECT, {
+      tarballPath,
+      overwrite: true,
+      promptDirectoryName,
+    });
+
+    expect(result.destinationDirectoryPath).toEqual(directoryPath);
+    expect(promptDirectoryName).not.toHaveBeenCalled();
+    expect(fs.existsSync(path.join(directoryPath, "existing.txt"))).toBe(true);
+    expect(fs.existsSync(path.join(directoryPath, "messagevisor.config.js"))).toBe(true);
+  });
+
+  it("fails clearly for non-interactive non-empty current directories", async function () {
+    const directoryPath = await createDestinationDirectory();
+    const tarballPath = await getFixtureTarballPath();
+    await fs.promises.writeFile(path.join(directoryPath, "existing.txt"), "hello");
+
+    await expect(
+      initProjectFromCLI(directoryPath, DEFAULT_PROJECT, {
+        tarballPath,
+        input: { isTTY: false } as NodeJS.ReadableStream & { isTTY: boolean },
+        output: { isTTY: false } as NodeJS.WritableStream & { isTTY: boolean },
+      }),
+    ).rejects.toThrow(
+      "Current working directory is not empty. Run `messagevisor init` from an empty directory, or pass --overwrite.",
+    );
+  });
+});

package/src/init/index.ts

@@ -0,0 +1,292 @@
+import * as fs from "fs";
+import * as path from "path";
+import { createInterface } from "readline/promises";
+import { Readable } from "stream";
+
+import type { Plugin } from "../cli";
+import { MessagevisorCLIError } from "../error";
+
+const tar: any = require("tar");
+
+export const DEFAULT_PROJECT = "yml";
+export const EXAMPLES_ORG_NAME = "messagevisor";
+export const EXAMPLES_REPO_NAME = "messagevisor";
+export const EXAMPLES_BRANCH_NAME = "main";
+export const EXAMPLES_TAR_URL = `https://codeload.github.com/${EXAMPLES_ORG_NAME}/${EXAMPLES_REPO_NAME}/tar.gz/${EXAMPLES_BRANCH_NAME}`;
+
+export interface InitProjectOptions {
+  overwrite?: boolean;
+  tarballUrl?: string;
+  tarballPath?: string;
+  fetchImpl?: typeof fetch;
+}
+
+export interface InitCommandOptions extends InitProjectOptions {
+  input?: NodeJS.ReadableStream & { isTTY?: boolean };
+  output?: NodeJS.WritableStream & { isTTY?: boolean };
+  promptDirectoryName?: (message: string) => Promise<string>;
+}
+
+export interface InitProjectResult {
+  project: string;
+  destinationDirectoryPath: string;
+  createdFileCount: number;
+  skippedConflictCount: number;
+}
+
+function getProjectArchivePath(projectName: string) {
+  return `${EXAMPLES_REPO_NAME}-${EXAMPLES_BRANCH_NAME}/projects/project-${projectName}/`;
+}
+
+function getExcludedReason(relativePath: string) {
+  const normalized = relativePath.replace(/\\/g, "/").replace(/\/+$/, "");
+
+  if (!normalized) {
+    return null;
+  }
+
+  const topLevelName = normalized.split("/")[0];
+
+  if (["datafiles", "catalog", "exports", "imports", "node_modules"].includes(topLevelName)) {
+    return "generated";
+  }
+
+  if (normalized === ".DS_Store" || normalized.endsWith("/.DS_Store")) {
+    return "generated";
+  }
+
+  if (
+    normalized === ".messagevisor/REVISION" ||
+    normalized.startsWith(".messagevisor/promotions/") ||
+    normalized.startsWith(".messagevisor/memory/") ||
+    /^\.messagevisor\/sets\/[^/]+\/REVISION$/.test(normalized)
+  ) {
+    return "generated";
+  }
+
+  return null;
+}
+
+async function assertDestinationReady(directoryPath: string, overwrite?: boolean) {
+  await fs.promises.mkdir(directoryPath, { recursive: true });
+  const entries = await fs.promises.readdir(directoryPath);
+
+  if (entries.length > 0 && !overwrite) {
+    throw new MessagevisorCLIError(
+      `Destination directory is not empty: ${directoryPath}. Pass --overwrite to initialize there and skip conflicting files.`,
+    );
+  }
+}
+
+async function isDirectoryEmpty(directoryPath: string) {
+  await fs.promises.mkdir(directoryPath, { recursive: true });
+  const entries = await fs.promises.readdir(directoryPath);
+
+  return entries.length === 0;
+}
+
+function getInitProjectOptions(options: InitCommandOptions): InitProjectOptions {
+  return {
+    overwrite: options.overwrite,
+    tarballUrl: options.tarballUrl,
+    tarballPath: options.tarballPath,
+    fetchImpl: options.fetchImpl,
+  };
+}
+
+function validateNewDirectoryName(directoryName: string) {
+  const trimmed = directoryName.trim();
+
+  if (!trimmed) {
+    throw new MessagevisorCLIError(
+      "Directory name is required to initialize a new Messagevisor project.",
+    );
+  }
+
+  if (
+    path.isAbsolute(trimmed) ||
+    trimmed.includes("/") ||
+    trimmed.includes("\\") ||
+    trimmed === "." ||
+    trimmed === ".."
+  ) {
+    throw new MessagevisorCLIError(
+      "Directory name must be a simple folder name, not an absolute path or nested path.",
+    );
+  }
+
+  return trimmed;
+}
+
+async function promptForNewDirectoryName(
+  message: string,
+  options: InitCommandOptions,
+): Promise<string> {
+  if (options.promptDirectoryName) {
+    return options.promptDirectoryName(message);
+  }
+
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+  const canPrompt = input.isTTY !== false && output.isTTY !== false;
+
+  if (!canPrompt) {
+    throw new MessagevisorCLIError(
+      "Current working directory is not empty. Run `messagevisor init` from an empty directory, or pass --overwrite.",
+    );
+  }
+
+  const readline = createInterface({ input, output });
+
+  try {
+    return readline.question(message);
+  } finally {
+    readline.close();
+  }
+}
+
+async function getTarballStream(options: InitProjectOptions = {}) {
+  if (options.tarballPath) {
+    return fs.createReadStream(options.tarballPath);
+  }
+
+  const fetchImpl = options.fetchImpl || fetch;
+  const response = await fetchImpl(options.tarballUrl || EXAMPLES_TAR_URL);
+
+  if (!response.ok || !response.body) {
+    throw new Error(
+      `Unable to download Messagevisor examples tarball: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  return Readable.fromWeb(response.body as any);
+}
+
+export async function initProject(
+  directoryPath: string,
+  projectName: string = DEFAULT_PROJECT,
+  options: InitProjectOptions = {},
+): Promise<InitProjectResult> {
+  await assertDestinationReady(directoryPath, options.overwrite);
+
+  const tarballStream = await getTarballStream(options);
+  const projectArchivePath = getProjectArchivePath(projectName);
+  let createdFileCount = 0;
+  let skippedConflictCount = 0;
+  let matchedProjectPath = false;
+
+  await new Promise<void>((resolve, reject) => {
+    tarballStream
+      .pipe(
+        tar.x({
+          cwd: directoryPath,
+          strip: 3,
+          filter: (archivePath, entry) => {
+            if (!archivePath.startsWith(projectArchivePath)) {
+              return false;
+            }
+
+            matchedProjectPath = true;
+            const relativePath = archivePath.slice(projectArchivePath.length);
+
+            if (!relativePath) {
+              return false;
+            }
+
+            if (getExcludedReason(relativePath)) {
+              return false;
+            }
+
+            const destinationPath = path.join(directoryPath, relativePath);
+            const entryType = (entry as any).type;
+
+            if (entryType !== "Directory" && fs.existsSync(destinationPath)) {
+              skippedConflictCount += 1;
+              return false;
+            }
+
+            if (entryType !== "Directory") {
+              createdFileCount += 1;
+            }
+
+            return true;
+          },
+        }),
+      )
+      .on("error", reject)
+      .on("finish", resolve);
+  });
+
+  if (!matchedProjectPath) {
+    throw new MessagevisorCLIError(
+      `Unknown project "${projectName}". No matching project-${projectName} found in examples tarball.`,
+    );
+  }
+
+  return {
+    project: projectName,
+    destinationDirectoryPath: directoryPath,
+    createdFileCount,
+    skippedConflictCount,
+  };
+}
+
+export async function initProjectFromCLI(
+  rootDirectoryPath: string,
+  projectName: string = DEFAULT_PROJECT,
+  options: InitCommandOptions = {},
+): Promise<InitProjectResult> {
+  if (options.overwrite || (await isDirectoryEmpty(rootDirectoryPath))) {
+    return initProject(rootDirectoryPath, projectName, getInitProjectOptions(options));
+  }
+
+  const directoryName = validateNewDirectoryName(
+    await promptForNewDirectoryName(
+      `Current working directory is not empty: ${rootDirectoryPath}\nEnter a new directory name to initialize Messagevisor project: `,
+      options,
+    ),
+  );
+  const destinationDirectoryPath = path.join(rootDirectoryPath, directoryName);
+
+  if (!(await isDirectoryEmpty(destinationDirectoryPath))) {
+    throw new MessagevisorCLIError(
+      `Destination directory is not empty: ${destinationDirectoryPath}. Please choose a different directory name.`,
+    );
+  }
+
+  return initProject(destinationDirectoryPath, projectName, getInitProjectOptions(options));
+}
+
+export const initPlugin: Plugin = {
+  command: "init",
+  handler: async ({ rootDirectoryPath, parsed }) => {
+    const result = await initProjectFromCLI(rootDirectoryPath, parsed.project || DEFAULT_PROJECT, {
+      overwrite: parsed.overwrite === true,
+    });
+
+    console.log(`Initialized Messagevisor project from "${result.project}"`);
+    console.log(`Destination directory: ${result.destinationDirectoryPath}`);
+    console.log(`Created files: ${result.createdFileCount}`);
+
+    if (result.skippedConflictCount > 0) {
+      console.log(`Skipped conflicts: ${result.skippedConflictCount}`);
+    }
+
+    console.log(``);
+    console.log(`Please run "npm install" in this directory.`);
+  },
+  examples: [
+    {
+      command: "init",
+      description: "initialize a Messagevisor project from the default yml starter",
+    },
+    {
+      command: "init --project=json",
+      description: "initialize a Messagevisor project from the json starter",
+    },
+    {
+      command: "init --project=environments",
+      description: "initialize a Messagevisor project from the sets-based environments starter",
+    },
+  ],
+};

package/src/lint/index.ts

@@ -0,0 +1 @@
+export { lintPlugin } from "../linter";

package/src/linter/attributeSchema.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+import { attributePropertyZodSchema, refineSchemaSemantics } from "./schema";
+
+export function getAttributeZodSchema() {
+  return attributePropertyZodSchema
+    .and(
+      z
+        .object({
+          key: z.string().optional(),
+          archived: z.boolean().optional(),
+          promotable: z.boolean().optional(),
+          description: z.string({
+            error: (issue) => (issue.input === undefined ? "Required" : undefined),
+          }),
+        })
+        .strict(),
+    )
+    .superRefine((data: any, ctx) => {
+      if (!data.type && !data.oneOf) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Attribute must define either \`type\` or \`oneOf\`.`,
+          path: ["type"],
+        });
+      }
+
+      if (data.type && data.oneOf) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Attribute cannot define both \`type\` and \`oneOf\`.`,
+          path: ["oneOf"],
+        });
+      }
+
+      refineSchemaSemantics(data, ctx);
+    });
+}