@verbatra/sdk 0.4.3 → 0.5.0-next.0

package/dist/index.d.cts

@@ -261,7 +261,7 @@ declare const verbatraConfigSchema: z.ZodObject<{
             glossaryId: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
     }, z.core.$strip>], "id">;
-    glossary: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    glossary: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodString>, z.ZodString]>>;
     tone: z.ZodOptional<z.ZodEnum<{
         formal: "formal";
         informal: "informal";
@@ -271,7 +271,22 @@ declare const verbatraConfigSchema: z.ZodObject<{
     generatePlurals: z.ZodOptional<z.ZodBoolean>;
     maxBatchSize: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
-type VerbatraConfig = z.infer<typeof verbatraConfigSchema>;
+/**
+ * The as-authored (or as-parsed) shape of the verbatra configuration, straight from the schema: `glossary`
+ * is still the union of an inline record or a file path. {@link defineConfig} and the authoring types are
+ * built on this; `loadConfig` accepts it as input and produces the resolved {@link VerbatraConfig}.
+ */
+type VerbatraConfigInput = z.infer<typeof verbatraConfigSchema>;
+/**
+ * The verbatra configuration after `loadConfig` has resolved it: identical to {@link VerbatraConfigInput}
+ * except `glossary`, which is always a plain record here. A glossary given as a file path is read,
+ * parsed, and validated by the loader before a `VerbatraConfig` is produced, so every downstream
+ * consumer (the translation flow, `watch`, the CLI) keeps receiving the same resolved shape it always
+ * did.
+ */
+type VerbatraConfig = Omit<VerbatraConfigInput, "glossary"> & {
+    glossary?: Readonly<Record<string, string>>;
+};
 
 type KnownModels<M extends string> = M extends string ? (string extends M ? never : M) : never;
 type AuthoringVariant<Id extends ProviderId, M extends string> = Extract<ProviderConfig, {
@@ -294,17 +309,19 @@ type AuthoringProviderVariant = {
     }>;
 };
 /**
- * The authoring view of the whole config for a provider id: a {@link VerbatraConfig} whose `provider`
- * is that id's single authoring variant, so `options.model` offers only that provider's models. When
- * `TId` defaults to `ProviderId`, `provider` is the full authoring union. Every value here is assignable
- * to {@link VerbatraConfig}, since a model literal is a subtype of `string`.
+ * The authoring view of the whole config for a provider id: a {@link VerbatraConfigInput} whose
+ * `provider` is that id's single authoring variant, so `options.model` offers only that provider's
+ * models. `glossary` stays the as-authored union (inline record or file path); resolution happens only
+ * in `loadConfig`. When `TId` defaults to `ProviderId`, `provider` is the full authoring union. Every
+ * value here is assignable to {@link VerbatraConfigInput}, since a model literal is a subtype of
+ * `string`.
  */
-type AuthoringConfigFor<TId extends ProviderId = ProviderId> = Omit<VerbatraConfig, "provider"> & {
+type AuthoringConfigFor<TId extends ProviderId = ProviderId> = Omit<VerbatraConfigInput, "provider"> & {
     provider: AuthoringProviderVariant[TId];
 };
 /**
  * The authoring view of the whole config across every provider (the `TId = ProviderId`
- * case of {@link AuthoringConfigFor}): identical to {@link VerbatraConfig} except that
+ * case of {@link AuthoringConfigFor}): identical to {@link VerbatraConfigInput} except that
  * `provider` offers per-provider model completions.
  */
 type AuthoringConfig = AuthoringConfigFor;
@@ -316,16 +333,66 @@ type AuthoringConfig = AuthoringConfigFor;
  *
  * The model restriction is a static authoring constraint only: `loadConfig` validates `model` as a
  * non-empty string, so a model the installed provider SDK does not yet list is flagged in the editor
- * but still runs.
+ * but still runs. Likewise, `glossary` accepts either an inline record or a file path here; `loadConfig`
+ * resolves a path to a record before the translation flow ever sees it.
  *
  * @param config - The verbatra configuration object.
- * @returns The same config, typed as {@link VerbatraConfig}.
+ * @returns The same config, typed as {@link VerbatraConfigInput}.
  */
-declare function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfig;
-declare function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfig;
-declare function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraConfig;
-declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfig;
-declare function defineConfig(config: AuthoringConfig): VerbatraConfig;
+declare function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfigInput;
+declare function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfigInput;
+declare function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraConfigInput;
+declare function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfigInput;
+declare function defineConfig(config: AuthoringConfig): VerbatraConfigInput;
+
+/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
+type BoundedFileRead = {
+    readonly kind: "ok";
+    readonly content: string;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
+/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
+type BoundedBytesRead = {
+    readonly kind: "ok";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "too-large";
+};
+/**
+ * The minimal file-system surface the SDK needs. Reads are bounded and writes are atomic. Injectable so
+ * tests stay deterministic; the format adapters do their own file IO and bypass this seam.
+ */
+interface SdkFs {
+    /** Whether a readable file exists at the path. */
+    fileExists(path: string): Promise<boolean>;
+    /**
+     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the handle is
+     * fstat'd and the read never advances past the sized length, so swapping in a larger file cannot
+     * bypass the cap. A missing or unreadable path is "missing"; a file over the cap is "too-large".
+     */
+    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
+    /** Read a file as raw bytes with the same TOCTOU-safe, bounded discipline as {@link readFileBounded}. */
+    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
+    /** Write atomically: a temp file in the same directory, then rename over the target. */
+    writeFile(path: string, data: string): Promise<void>;
+    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
+    writeBytes(path: string, data: Uint8Array): Promise<void>;
+}
+
+/** Where a config's resolved glossary came from, recorded for later Studio consumption. */
+type GlossaryProvenance = {
+    readonly source: "none";
+} | {
+    readonly source: "inline";
+} | {
+    readonly source: "file";
+    readonly path: string;
+};
 
 interface LoadConfigOptions {
     /** Directory to start the search from. Defaults to the current working directory. */
@@ -342,7 +409,42 @@ interface LoadConfigOptions {
      * search, but `configOverride` takes precedence over it.
      */
     readonly configPath?: string;
+    /** The file-system seam a glossary file path is read through. Defaults to {@link defaultFs}. */
+    readonly fs?: SdkFs;
+}
+/** Where the loaded config came from: an in-memory override, one explicit file, or a search result. */
+type ConfigSource = {
+    readonly kind: "search" | "explicit";
+    readonly filepath: string;
+} | {
+    readonly kind: "override";
+};
+/**
+ * The result of {@link loadConfigWithMeta}: the resolved config, where it was loaded from, and where its
+ * glossary came from. `filepath` (when present) and a `glossary` file path are always absolute.
+ */
+interface LoadedConfig {
+    readonly config: VerbatraConfig;
+    readonly source: ConfigSource;
+    readonly glossary: GlossaryProvenance;
 }
+/**
+ * Load and validate the verbatra configuration, returning provenance alongside it: which source it was
+ * loaded from ({@link ConfigSource}), and whether its glossary is absent, inline, or resolved from a
+ * file ({@link GlossaryProvenance}). {@link loadConfig} is a thin wrapper that returns only the
+ * `config` field; use this directly when the provenance is needed (for example, to display it or to
+ * re-resolve a glossary file relative to the same base directory).
+ *
+ * @param options - Where/what to load: `cwd`, an in-memory `configOverride`, an explicit `configPath`,
+ *   or a `fs` seam override.
+ * @returns The resolved {@link VerbatraConfig}, its {@link ConfigSource}, and its {@link GlossaryProvenance}.
+ * @throws {@link SdkError} `CONFIG_NOT_FOUND`: no config was found by search, or the explicit `configPath`
+ *   does not exist.
+ * @throws {@link SdkError} `CONFIG_INVALID`: a config was found but is unparseable or fails validation, or
+ *   its glossary file path could not be read as a valid, UTF-8, flat string record (a raw error never
+ *   escapes).
+ */
+declare function loadConfigWithMeta(options?: LoadConfigOptions): Promise<LoadedConfig>;
 /**
  * Load and validate the verbatra configuration. Supports a code-defined
  * verbatra.config.ts and file-based configs (.verbatrarc.json/.yaml, package.json
@@ -352,12 +454,17 @@ interface LoadConfigOptions {
  *
  * Precedence: `configOverride` (validate in-memory) > `configPath` (load one explicit file) > search.
  *
+ * A `glossary` given as a file path is read, parsed, and validated at load time (see
+ * {@link loadConfigWithMeta} for its provenance); a relative path resolves against the loaded config
+ * file's directory, or against `cwd` for a `configOverride`. Watch mode does not re-resolve a glossary
+ * file on later edits; restart to pick up a change.
+ *
  * @param options - Where/what to load: `cwd`, an in-memory `configOverride`, or an explicit `configPath`.
  * @returns The validated {@link VerbatraConfig}.
  * @throws {@link SdkError} `CONFIG_NOT_FOUND`: no config was found by search, or the explicit `configPath`
  *   does not exist.
- * @throws {@link SdkError} `CONFIG_INVALID`: a config was found but is unparseable or fails validation
- *   (a raw zod error never escapes).
+ * @throws {@link SdkError} `CONFIG_INVALID`: a config was found but is unparseable or fails validation, or
+ *   its glossary file path could not be resolved (a raw error never escapes).
  * @example
  * ```ts
  * import { loadConfig, translate } from "@verbatra/sdk";
@@ -570,45 +677,6 @@ declare class AdapterRegistry {
     resolve(filePath: string, options?: ResolveOptions): AdapterResolution;
 }
 
-/** Outcome of a bounded read: the content, or why it could not be read in bounds. */
-type BoundedFileRead = {
-    readonly kind: "ok";
-    readonly content: string;
-} | {
-    readonly kind: "missing";
-} | {
-    readonly kind: "too-large";
-};
-/** Outcome of a bounded binary read: the bytes, or why they could not be read in bounds. */
-type BoundedBytesRead = {
-    readonly kind: "ok";
-    readonly bytes: Uint8Array;
-} | {
-    readonly kind: "missing";
-} | {
-    readonly kind: "too-large";
-};
-/**
- * The minimal file-system surface the SDK needs. Reads are bounded and writes are atomic. Injectable so
- * tests stay deterministic; the format adapters do their own file IO and bypass this seam.
- */
-interface SdkFs {
-    /** Whether a readable file exists at the path. */
-    fileExists(path: string): Promise<boolean>;
-    /**
-     * Read a file as UTF-8 through a single handle, bounded to maxBytes. TOCTOU-safe: the handle is
-     * fstat'd and the read never advances past the sized length, so swapping in a larger file cannot
-     * bypass the cap. A missing or unreadable path is "missing"; a file over the cap is "too-large".
-     */
-    readFileBounded(path: string, maxBytes: number): Promise<BoundedFileRead>;
-    /** Read a file as raw bytes with the same TOCTOU-safe, bounded discipline as {@link readFileBounded}. */
-    readBytesBounded(path: string, maxBytes: number): Promise<BoundedBytesRead>;
-    /** Write atomically: a temp file in the same directory, then rename over the target. */
-    writeFile(path: string, data: string): Promise<void>;
-    /** Write raw bytes atomically (temp file, then rename over the target). Used for the workbook. */
-    writeBytes(path: string, data: Uint8Array): Promise<void>;
-}
-
 /** Per-locale drift status: counts only, no key lists. */
 interface LocaleCheckSummary {
     /** The target locale this entry reports on. */
@@ -708,8 +776,63 @@ interface DiffDeps {
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
+/** Per-locale key count and drift against the source and target files, from the recorded lock baseline. */
+interface LockLocaleState {
+    /** The target locale this entry reports on. */
+    readonly locale: string;
+    /** Number of keys the lock records a baseline for, in this locale. */
+    readonly keyCount: number;
+    /** Keys present in source but absent from the target. */
+    readonly missing: number;
+    /** Keys whose source changed since the target was last translated. */
+    readonly stale: number;
+    /** Keys whose recorded baseline still matches the source. */
+    readonly upToDate: number;
+}
+/**
+ * The lock-file's existence, version, and per-locale drift. `exists` is the outcome of an explicit
+ * probe of the lock-file path, never inferred from {@link readLockFile}'s missing-file degrade, so
+ * "no lock-file yet" and "an empty but present lock-file" stay distinguishable.
+ */
+type LockStateResult = {
+    readonly exists: false;
+} | {
+    readonly exists: true;
+    readonly version: number;
+    readonly locales: readonly LockLocaleState[];
+};
+/** Input for {@link lockState}: the validated config and which locales to report on. */
+interface LockStateInput {
+    /** The validated configuration (typically from {@link loadConfig}). */
+    readonly config: VerbatraConfig;
+    /** Directory the file pattern and lock-file resolve against; defaults to cwd. */
+    readonly cwd?: string;
+    /** Subset of target locales to report on; defaults to all configured target locales. */
+    readonly locales?: readonly string[];
+}
+/** Composition seam for {@link lockState}: inject a registry and a file system for tests. */
+interface LockStateDeps {
+    readonly adapterRegistry?: AdapterRegistry;
+    readonly fs?: SdkFs;
+}
+/**
+ * Report the lock-file's existence, version, and per-locale drift (key count from the recorded
+ * baseline, plus missing, stale, and up-to-date counts against the current source and target),
+ * without calling a provider, writing any file, or mutating the lock. `exists` comes from an
+ * explicit probe of the lock-file path: when it is absent, the result is `{ exists: false }` and
+ * no source or target file is read, since there is no recorded baseline to report drift against.
+ *
+ * @param input - The validated config and which locales to report on.
+ * @param deps - Optional composition seams (registry, file system) for tests.
+ * @returns The lock-file's existence and, when present, its version and per-locale drift.
+ * @throws {@link SdkError} `UNKNOWN_LOCALE` when a requested locale is not among the configured
+ *   target locales; when the lock-file exists, also `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`,
+ *   `SOURCE_INVALID`, or `LOCK_FILE_INVALID` with the same meanings as in `translate`.
+ */
+declare function lockState(input: LockStateInput, deps?: LockStateDeps): Promise<LockStateResult>;
+
 /** A stable code for an SDK-originated notice (not a provider notice). */
-type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED";
+type SdkNoticeCode = "PLURAL_CATEGORIES_INCOMPLETE" | "SUB_BATCH_FAILED" | "BLANK_ROW_BASELINE_RETAINED";
 /**
  * A notice raised by the SDK itself (not a provider), structurally identical to a {@link ProviderNotice}
  * so both share the {@link LocaleSummary.notices} channel. Carries only a stable code and a static,
@@ -746,8 +869,20 @@ interface LocaleSummary {
     readonly pruned: readonly string[];
     /** Source keys flagged invalid-ICU that were skipped for translation this run. */
     readonly invalidIcuSource: readonly string[];
-    /** Translated keys that failed the placeholder-integrity check and were withheld. */
+    /**
+     * Translated keys that failed the placeholder-integrity check and were withheld. Never includes a
+     * key withheld because the provider call itself failed; see {@link LocaleSummary.providerFailures}
+     * for that case.
+     */
     readonly integrityMismatches: readonly string[];
+    /**
+     * Keys withheld because the provider call itself failed (for example a revoked API key, a rate
+     * limit, or a network timeout), as distinct from a translation that came back and failed the
+     * placeholder-integrity check. Nothing was translated for these keys. The corresponding
+     * {@link LocaleSummary.notices} entry carries the secret-free failure code and message. Empty in a
+     * dry-run and empty unless a provider call threw.
+     */
+    readonly providerFailures: readonly string[];
     /**
      * Plural-category keys verbatra synthesized this run (for example a Polish `items_few` the source
      * never supplied), kept distinct from {@link translated}. Empty unless plural generation was enabled
@@ -944,6 +1079,42 @@ interface ImportWorkbookDeps {
  */
 declare function importWorkbook(input: ImportWorkbookInput, deps?: ImportWorkbookDeps): Promise<RunSummary>;
 
+/**
+ * The lock-file shape: for each target locale, a map of key to the source content hash from which that
+ * target key was last translated. The baseline core's diff consumes to detect changed source strings.
+ */
+interface LockFile {
+    readonly version: number;
+    readonly locales: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+
+/** Input for {@link loadLockFile}: the directory the lock-file resolves against. */
+interface LoadLockFileInput {
+    /** Directory the lock-file resolves against; defaults to cwd. */
+    readonly cwd?: string;
+}
+/** Composition seam for {@link loadLockFile}: inject a file system for tests. */
+interface LoadLockFileDeps {
+    readonly fs?: SdkFs;
+}
+/**
+ * Read the project's lock-file: a thin public wrapper around the internal lock-file reader,
+ * following the same input/deps convention as {@link check}, {@link diff}, and {@link lockState}.
+ * A missing lock-file degrades to an empty lock (first-run), the same behavior `translate` and
+ * `watch` rely on internally. Callers that need to distinguish "no lock-file yet" from "an empty
+ * but present lock-file" should use {@link lockState} instead, which probes the file's existence
+ * explicitly.
+ *
+ * @param input - The directory the lock-file resolves against.
+ * @param deps - Optional composition seam (file system) for tests.
+ * @returns The parsed lock-file, or an empty lock when none exists yet.
+ * @throws {@link SdkError} `LOCK_FILE_INVALID` when the lock-file is present but corrupt or oversized.
+ */
+declare function loadLockFile(input?: LoadLockFileInput, deps?: LoadLockFileDeps): Promise<LockFile>;
+
+/** The committed lock-file name, chosen to be obviously JSON and to not match a `*.lock` ignore rule. */
+declare const LOCK_FILE_NAME = "verbatra.lock.json";
+
 /**
  * Read-only metadata the CLI `init` scaffold derives its tables from, so the CLI never restates the
  * provider, env-var, model, or format truth owned by core and ai-providers.
@@ -1058,4 +1229,4 @@ interface WatchController {
  */
 declare function watch(input: WatchInput, deps?: WatchDeps): Promise<WatchController>;
 
-export { type CheckDeps, type CheckInput, type CheckSummary, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type ImportWorkbookDeps, type ImportWorkbookInput, type LoadConfigOptions, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, scaffoldingMetadata, translate, verbatraConfigSchema, watch };
+export { type CheckDeps, type CheckInput, type CheckSummary, type ConfigSource, type CreateProvider, type CreateWatcher, DEFAULT_WORKBOOK_PATH, type DiffDeps, type DiffInput, type DiffSummary, type ExportWorkbookDeps, type ExportWorkbookInput, type ExportWorkbookResult, type GlossaryProvenance, type ImportWorkbookDeps, type ImportWorkbookInput, LOCK_FILE_NAME, type LoadConfigOptions, type LoadLockFileDeps, type LoadLockFileInput, type LoadedConfig, type LocaleCheckSummary, type LocaleDiff, type LocaleNotice, type LocaleSummary, type LockFile, type LockLocaleState, type LockStateDeps, type LockStateInput, type LockStateResult, type ProviderConfig, type ProviderId, type RunSummary, type RunTranslate, SdkError, type SdkErrorCode, type SdkFs, type SdkNotice, type SdkNoticeCode, type SupportedFormat$1 as SupportedFormat, type TranslateDeps, type TranslateInput, type VerbatraConfig, type VerbatraConfigInput, type WatchController, type WatchDeps, type WatchInput, type WatchRunResult, type Watcher, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, loadConfigWithMeta, loadLockFile, lockState, scaffoldingMetadata, translate, verbatraConfigSchema, watch };