@verbatra/sdk 0.4.4 → 0.5.0-next.0

package/dist/index.js

@@ -1,7 +1,9 @@
 import { existsSync } from 'fs';
-import { resolve, join, dirname, basename, extname } from 'path';
+import { dirname, resolve, join, basename, extname } from 'path';
 import { cosmiconfig } from 'cosmiconfig';
 import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
+import { randomUUID } from 'crypto';
+import { access, writeFile, rename, rm, open } from 'fs/promises';
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
 import * as deepl from 'deepl-node';
@@ -9,8 +11,6 @@ import { createRequire } from 'module';
 import log from 'loglevel';
 import { GoogleGenAI } from '@google/genai';
 import OpenAI from 'openai';
-import { randomUUID } from 'crypto';
-import { access, writeFile, rename, rm, open } from 'fs/promises';
 import { parse as parse$1, TYPE } from '@formatjs/icu-messageformat-parser';
 import { XMLSerializer, DOMParser } from '@xmldom/xmldom';
 import { stringify, parse } from 'yaml';
@@ -38,6 +38,155 @@ var SdkError = class extends Error {
     this.code = code;
   }
 };
+async function readBoundedUtf8(handle, size) {
+  const buffer = Buffer.allocUnsafe(size);
+  let offset = 0;
+  while (offset < size) {
+    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+    if (bytesRead === 0) {
+      break;
+    }
+    offset += bytesRead;
+  }
+  return buffer.toString("utf8", 0, offset);
+}
+async function readBounded(path, maxBytes) {
+  let handle;
+  try {
+    handle = await open(path, "r");
+  } catch {
+    return { kind: "missing" };
+  }
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) {
+      return { kind: "missing" };
+    }
+    if (info.size > maxBytes) {
+      return { kind: "too-large" };
+    }
+    return { kind: "ok", content: await readBoundedUtf8(handle, info.size) };
+  } finally {
+    await handle.close();
+  }
+}
+async function readBoundedBytesInto(handle, size) {
+  const buffer = Buffer.allocUnsafeSlow(size);
+  let offset = 0;
+  while (offset < size) {
+    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+    if (bytesRead === 0) {
+      break;
+    }
+    offset += bytesRead;
+  }
+  return new Uint8Array(buffer.buffer, buffer.byteOffset, offset);
+}
+async function readBoundedBytes(path, maxBytes) {
+  let handle;
+  try {
+    handle = await open(path, "r");
+  } catch {
+    return { kind: "missing" };
+  }
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) {
+      return { kind: "missing" };
+    }
+    if (info.size > maxBytes) {
+      return { kind: "too-large" };
+    }
+    return { kind: "ok", bytes: await readBoundedBytesInto(handle, info.size) };
+  } finally {
+    await handle.close();
+  }
+}
+function tempFileName(path) {
+  return join(dirname(path), `.${basename(path)}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`);
+}
+async function atomicWrite(path, data) {
+  const tmp = tempFileName(path);
+  await (typeof data === "string" ? writeFile(tmp, data, "utf8") : writeFile(tmp, data));
+  try {
+    await rename(tmp, path);
+  } catch (error) {
+    await rm(tmp, { force: true });
+    throw error;
+  }
+}
+var defaultFs = {
+  async fileExists(path) {
+    try {
+      await access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  readFileBounded: (path, maxBytes) => readBounded(path, maxBytes),
+  readBytesBounded: (path, maxBytes) => readBoundedBytes(path, maxBytes),
+  writeFile: (path, data) => atomicWrite(path, data),
+  writeBytes: (path, data) => atomicWrite(path, data)
+};
+var MAX_GLOSSARY_FILE_BYTES = 1024 * 1024;
+var glossaryRecordSchema = z.record(z.string(), z.string());
+var BOM = "\uFEFF";
+var REPLACEMENT_CHARACTER = "\uFFFD";
+var NUL = "\0";
+function stripBom(content) {
+  return content.startsWith(BOM) ? content.slice(BOM.length) : content;
+}
+function looksLikeInvalidEncoding(content) {
+  return content.startsWith(REPLACEMENT_CHARACTER) || content.includes(NUL);
+}
+async function readGlossaryFile(resolvedPath, fs) {
+  const read = await fs.readFileBounded(resolvedPath, MAX_GLOSSARY_FILE_BYTES);
+  if (read.kind === "missing") {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The glossary file at ${resolvedPath} was not found or could not be read.`
+    );
+  }
+  if (read.kind === "too-large") {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The glossary file at ${resolvedPath} exceeds the maximum allowed size of ${MAX_GLOSSARY_FILE_BYTES} bytes.`
+    );
+  }
+  const content = stripBom(read.content);
+  if (looksLikeInvalidEncoding(content)) {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The glossary file at ${resolvedPath} must be UTF-8 encoded.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new SdkError("CONFIG_INVALID", `The glossary file at ${resolvedPath} is not valid JSON.`);
+  }
+  const result = glossaryRecordSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The glossary file at ${resolvedPath} must contain a flat object of string keys to string values.`
+    );
+  }
+  return result.data;
+}
+async function resolveGlossary(glossary, baseDir, fs) {
+  if (glossary === void 0) {
+    return { glossary: void 0, provenance: { source: "none" } };
+  }
+  if (typeof glossary === "string") {
+    const resolvedPath = resolve(baseDir, glossary);
+    const record = await readGlossaryFile(resolvedPath, fs);
+    return { glossary: record, provenance: { source: "file", path: resolvedPath } };
+  }
+  return { glossary, provenance: { source: "inline" } };
+}
 var FNV_OFFSET_BASIS = 14695981039346656037n;
 var FNV_PRIME = 1099511628211n;
 var U64_MASK = (1n << 64n) - 1n;
@@ -873,7 +1022,13 @@ var verbatraConfigSchema = z.strictObject({
     pattern: z.string().min(1)
   }),
   provider: providerConfigSchema,
-  glossary: z.record(z.string(), z.string()).optional(),
+  /**
+   * A glossary of source terms to preferred target terms, either inline or as a path to a JSON file
+   * carrying the same shape. The two forms are mutually exclusive by type; there is no merge or
+   * precedence between them. A path is resolved and validated by the loader, not by this schema; see
+   * `resolve-glossary.ts`.
+   */
+  glossary: z.union([z.record(z.string(), z.string()), z.string().min(1)]).optional(),
   tone: z.enum(["formal", "informal", "neutral"]).optional(),
   /**
    * Opt-in orphan pruning, off by default. When true, keys present in a target file but absent from
@@ -927,7 +1082,7 @@ function formatIssues(error) {
     return issue.code === "unrecognized_keys" ? `${base} (API keys are read from the environment, not the config)` : base;
   }).join("; ");
 }
-function validate(input) {
+function parseConfig(input) {
   const parsed = verbatraConfigSchema.safeParse(input);
   if (!parsed.success) {
     throw new SdkError(
@@ -937,7 +1092,16 @@ function validate(input) {
   }
   return parsed.data;
 }
-async function loadExplicit(explorer, configPath, cwd) {
+async function finalizeConfig(parsed, baseDir, fs) {
+  const { glossary: glossaryInput, ...rest } = parsed;
+  const resolved = await resolveGlossary(glossaryInput, baseDir, fs);
+  const config = {
+    ...rest,
+    ...resolved.glossary !== void 0 ? { glossary: resolved.glossary } : {}
+  };
+  return { config, glossary: resolved.provenance };
+}
+async function loadExplicitWithMeta(explorer, configPath, cwd, fs) {
   const resolved = resolve(cwd ?? process.cwd(), configPath);
   if (!existsSync(resolved)) {
     throw new SdkError("CONFIG_NOT_FOUND", `No verbatra configuration file at ${resolved}.`);
@@ -949,18 +1113,23 @@ async function loadExplicit(explorer, configPath, cwd) {
     const detail = error instanceof Error ? error.message : String(error);
     throw new SdkError("CONFIG_INVALID", `Failed to load the verbatra configuration: ${detail}`);
   }
-  return validate(result?.config);
+  const parsed = parseConfig(result?.config);
+  const { config, glossary } = await finalizeConfig(parsed, dirname(resolved), fs);
+  return { config, source: { kind: "explicit", filepath: resolved }, glossary };
 }
-async function loadConfig(options = {}) {
+async function loadConfigWithMeta(options = {}) {
+  const fs = options.fs ?? defaultFs;
   if (options.configOverride !== void 0) {
-    return validate(options.configOverride);
+    const parsed2 = parseConfig(options.configOverride);
+    const { config: config2, glossary: glossary2 } = await finalizeConfig(parsed2, options.cwd ?? process.cwd(), fs);
+    return { config: config2, source: { kind: "override" }, glossary: glossary2 };
   }
   const explorer = cosmiconfig(MODULE_NAME, {
     searchPlaces: SEARCH_PLACES,
     loaders: { ".ts": TypeScriptLoader() }
   });
   if (options.configPath !== void 0) {
-    return loadExplicit(explorer, options.configPath, options.cwd);
+    return loadExplicitWithMeta(explorer, options.configPath, options.cwd, fs);
   }
   let result;
   try {
@@ -975,99 +1144,14 @@ async function loadConfig(options = {}) {
       "No verbatra configuration found. Create a verbatra.config.ts, a .verbatrarc.json, or a 'verbatra' property in package.json."
     );
   }
-  return validate(result.config);
-}
-async function readBoundedUtf8(handle, size) {
-  const buffer = Buffer.allocUnsafe(size);
-  let offset = 0;
-  while (offset < size) {
-    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
-    if (bytesRead === 0) {
-      break;
-    }
-    offset += bytesRead;
-  }
-  return buffer.toString("utf8", 0, offset);
-}
-async function readBounded(path, maxBytes) {
-  let handle;
-  try {
-    handle = await open(path, "r");
-  } catch {
-    return { kind: "missing" };
-  }
-  try {
-    const info = await handle.stat();
-    if (!info.isFile()) {
-      return { kind: "missing" };
-    }
-    if (info.size > maxBytes) {
-      return { kind: "too-large" };
-    }
-    return { kind: "ok", content: await readBoundedUtf8(handle, info.size) };
-  } finally {
-    await handle.close();
-  }
-}
-async function readBoundedBytesInto(handle, size) {
-  const buffer = Buffer.allocUnsafeSlow(size);
-  let offset = 0;
-  while (offset < size) {
-    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
-    if (bytesRead === 0) {
-      break;
-    }
-    offset += bytesRead;
-  }
-  return new Uint8Array(buffer.buffer, buffer.byteOffset, offset);
-}
-async function readBoundedBytes(path, maxBytes) {
-  let handle;
-  try {
-    handle = await open(path, "r");
-  } catch {
-    return { kind: "missing" };
-  }
-  try {
-    const info = await handle.stat();
-    if (!info.isFile()) {
-      return { kind: "missing" };
-    }
-    if (info.size > maxBytes) {
-      return { kind: "too-large" };
-    }
-    return { kind: "ok", bytes: await readBoundedBytesInto(handle, info.size) };
-  } finally {
-    await handle.close();
-  }
-}
-function tempFileName(path) {
-  return join(dirname(path), `.${basename(path)}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`);
+  const parsed = parseConfig(result.config);
+  const { config, glossary } = await finalizeConfig(parsed, dirname(result.filepath), fs);
+  return { config, source: { kind: "search", filepath: result.filepath }, glossary };
 }
-async function atomicWrite(path, data) {
-  const tmp = tempFileName(path);
-  await (typeof data === "string" ? writeFile(tmp, data, "utf8") : writeFile(tmp, data));
-  try {
-    await rename(tmp, path);
-  } catch (error) {
-    await rm(tmp, { force: true });
-    throw error;
-  }
+async function loadConfig(options = {}) {
+  const { config } = await loadConfigWithMeta(options);
+  return config;
 }
-var defaultFs = {
-  async fileExists(path) {
-    try {
-      await access(path);
-      return true;
-    } catch {
-      return false;
-    }
-  },
-  readFileBounded: (path, maxBytes) => readBounded(path, maxBytes),
-  readBytesBounded: (path, maxBytes) => readBoundedBytes(path, maxBytes),
-  writeFile: (path, data) => atomicWrite(path, data),
-  writeBytes: (path, data) => atomicWrite(path, data)
-};
 var LOCK_FILE_NAME = "verbatra.lock.json";
 var CURRENT_VERSION = 1;
 var EMPTY_LOCK = { version: CURRENT_VERSION, locales: {} };
@@ -2224,6 +2308,40 @@ async function diff(input, deps = {}) {
   return { hasPendingChanges: locales.some((entry) => entry.hasPendingChanges), locales };
 }
 
+// src/flow/lock-state.ts
+function toLockLocaleState(locale, keyCount, diff2) {
+  return {
+    locale,
+    keyCount,
+    missing: diff2.missing.length,
+    stale: diff2.changed.length,
+    upToDate: diff2.unchanged.length
+  };
+}
+async function lockState(input, deps = {}) {
+  const config = input.config;
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const locales = selectLocales(config, input.locales);
+  const path = lockFilePath(cwd);
+  const exists = await fs.fileExists(path);
+  if (!exists) {
+    return { exists: false };
+  }
+  const lock = await readLockFile(path, fs);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const source = await readSource(config, cwd, fs, adapter);
+  const localeStates = await Promise.all(
+    locales.map(async (locale) => {
+      const target = await readTarget(cwd, config, adapter, fs, locale);
+      const baseline = baselineFor(lock, locale);
+      const diff2 = diffResources(source.resource, target, { baseline });
+      return toLockLocaleState(locale, baseline.size, diff2);
+    })
+  );
+  return { exists: true, version: lock.version, locales: localeStates };
+}
+
 // src/selection/select-provider.ts
 function selectProvider(config, createProvider = buildProvider) {
   try {
@@ -3429,6 +3547,13 @@ async function importWorkbook(input, deps = {}) {
   return { dryRun, locales: summaries, succeeded, failed };
 }
 
+// src/lock/load-lock-file.ts
+async function loadLockFile(input = {}, deps = {}) {
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  return readLockFile(lockFilePath(cwd), fs);
+}
+
 // src/scaffolding.ts
 var scaffoldingMetadata = {
   /** Provider id -> the environment variable its API key is read from. Owned by ai-providers. */
@@ -3544,6 +3669,6 @@ async function watch(input, deps = {}) {
   return { stop };
 }
 
-export { DEFAULT_WORKBOOK_PATH, SdkError, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, scaffoldingMetadata, translate2 as translate, verbatraConfigSchema, watch };
+export { DEFAULT_WORKBOOK_PATH, LOCK_FILE_NAME, SdkError, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate2 as translate, verbatraConfigSchema, watch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map