@verbatra/sdk 0.4.4 → 0.5.0-next.0

package/dist/index.cjs

@@ -4,6 +4,8 @@ var fs = require('fs');
 var path = require('path');
 var cosmiconfig = require('cosmiconfig');
 var cosmiconfigTypescriptLoader = require('cosmiconfig-typescript-loader');
+var crypto = require('crypto');
+var promises = require('fs/promises');
 var zod = require('zod');
 var Anthropic = require('@anthropic-ai/sdk');
 var deepl = require('deepl-node');
@@ -11,8 +13,6 @@ var module$1 = require('module');
 var log = require('loglevel');
 var genai = require('@google/genai');
 var OpenAI = require('openai');
-var crypto = require('crypto');
-var promises = require('fs/promises');
 var icuMessageformatParser = require('@formatjs/icu-messageformat-parser');
 var xmldom = require('@xmldom/xmldom');
 var yaml = require('yaml');
@@ -68,6 +68,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 promises.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 promises.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$1) {
+  return path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`);
+}
+async function atomicWrite(path, data) {
+  const tmp = tempFileName(path);
+  await (typeof data === "string" ? promises.writeFile(tmp, data, "utf8") : promises.writeFile(tmp, data));
+  try {
+    await promises.rename(tmp, path);
+  } catch (error) {
+    await promises.rm(tmp, { force: true });
+    throw error;
+  }
+}
+var defaultFs = {
+  async fileExists(path) {
+    try {
+      await promises.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 = zod.z.record(zod.z.string(), zod.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 = path.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;
@@ -903,7 +1052,13 @@ var verbatraConfigSchema = zod.z.strictObject({
     pattern: zod.z.string().min(1)
   }),
   provider: providerConfigSchema,
-  glossary: zod.z.record(zod.z.string(), zod.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: zod.z.union([zod.z.record(zod.z.string(), zod.z.string()), zod.z.string().min(1)]).optional(),
   tone: zod.z.enum(["formal", "informal", "neutral"]).optional(),
   /**
    * Opt-in orphan pruning, off by default. When true, keys present in a target file but absent from
@@ -957,7 +1112,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(
@@ -967,7 +1122,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$1) {
   const resolved = path.resolve(cwd ?? process.cwd(), configPath);
   if (!fs.existsSync(resolved)) {
     throw new SdkError("CONFIG_NOT_FOUND", `No verbatra configuration file at ${resolved}.`);
@@ -979,18 +1143,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, path.dirname(resolved), fs$1);
+  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.cosmiconfig(MODULE_NAME, {
     searchPlaces: SEARCH_PLACES,
     loaders: { ".ts": cosmiconfigTypescriptLoader.TypeScriptLoader() }
   });
   if (options.configPath !== void 0) {
-    return loadExplicit(explorer, options.configPath, options.cwd);
+    return loadExplicitWithMeta(explorer, options.configPath, options.cwd, fs);
   }
   let result;
   try {
@@ -1005,99 +1174,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 promises.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 promises.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$1) {
-  return path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`);
+  const parsed = parseConfig(result.config);
+  const { config, glossary } = await finalizeConfig(parsed, path.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" ? promises.writeFile(tmp, data, "utf8") : promises.writeFile(tmp, data));
-  try {
-    await promises.rename(tmp, path);
-  } catch (error) {
-    await promises.rm(tmp, { force: true });
-    throw error;
-  }
+async function loadConfig(options = {}) {
+  const { config } = await loadConfigWithMeta(options);
+  return config;
 }
-var defaultFs = {
-  async fileExists(path) {
-    try {
-      await promises.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: {} };
@@ -2254,6 +2338,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 {
@@ -3459,6 +3577,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. */
@@ -3575,6 +3700,7 @@ async function watch(input, deps = {}) {
 }
 
 exports.DEFAULT_WORKBOOK_PATH = DEFAULT_WORKBOOK_PATH;
+exports.LOCK_FILE_NAME = LOCK_FILE_NAME;
 exports.SdkError = SdkError;
 exports.check = check;
 exports.defineConfig = defineConfig;
@@ -3582,6 +3708,9 @@ exports.diff = diff;
 exports.exportWorkbook = exportWorkbook;
 exports.importWorkbook = importWorkbook;
 exports.loadConfig = loadConfig;
+exports.loadConfigWithMeta = loadConfigWithMeta;
+exports.loadLockFile = loadLockFile;
+exports.lockState = lockState;
 exports.scaffoldingMetadata = scaffoldingMetadata;
 exports.translate = translate2;
 exports.verbatraConfigSchema = verbatraConfigSchema;