@i18nprune/core 0.1.0

package/dist/generate.d.ts

@@ -0,0 +1,487 @@
+import { T as TranslateContext, a as TranslationTickProgressOptions, I as IdentityStreakGuard, b as TranslationTickProgressFn, P as ProviderAttemptOutcome, c as TranslateFailureOutcome, G as GenerateResumeRefContext, d as TranslateRunPartialStats, H as HandoffEligibilityRow, e as GenerateTranslateCache, f as GenerateResumeCandidateLeafInput } from './resumeCandidates-xR13eEwt.js';
+import { C as CoreContext, T as TranslationSurfaceLeaf } from './coreContext-DMaWLvmB.js';
+export { c as CoreResolvedPaths } from './coreContext-DMaWLvmB.js';
+import { I as Issue } from './index-X50E1FIX.js';
+import { L as LocaleMetadataReport } from './index-DLwTogCo.js';
+import { T as TranslationProviderId } from './providers-0uMEfT6q.js';
+import { a as RunEvent, R as RunEmitter } from './index-BgG01AKL.js';
+import { b as TranslateTargetLanguage, c as Translator, R as ResolveLocaleLeafModeInput } from './index-B_ow_Xvr.js';
+import { S as StringLeaf } from './index-BQuLEQ9b.js';
+import { a as PreservePolicy, P as ParityPolicy, E as EffectiveReferenceConfig } from './root-2-kCaBvQ.js';
+import { a as TranslateStartRateLimit } from './translate-CIHYp7wi.js';
+import { r as resolveLocaleLeafMode } from './modeResolve-cGVaY5Hh.js';
+import './adapters-gp1lXp0T.js';
+import './capabilities-x74cD2Hu.js';
+import './fs-BUYD8ZhA.js';
+import './path-Bfn3SAts.js';
+import 'zod';
+
+declare function createCoreContext(input: {
+    config: CoreContext['config'];
+    adapters: CoreContext['adapters'];
+    env: CoreContext['env'];
+    paths: CoreContext['paths'];
+    configFileLoaded?: CoreContext['configFileLoaded'];
+    run?: CoreContext['run'];
+    cache?: CoreContext['cache'];
+    localeRead?: CoreContext['localeRead'];
+}): CoreContext;
+/** Project-wide ops pass this into {@link runTranslate} / translator helpers that only need the translate block. */
+declare function translateContextFromCore(ctx: CoreContext): TranslateContext;
+
+/** Display metadata for a generate target, resolved from the bundled language catalog. */
+type GenerateLocaleDisplay = {
+    /** English label from catalog (falls back to target code). */
+    englishName: string;
+    /** Native endonym from catalog (falls back to target code). */
+    nativeName: string;
+    /** Layout direction from catalog or RTL heuristic. */
+    direction: 'ltr' | 'rtl';
+};
+
+/**
+ * Thrown when the streak guard decides not to proceed (cap reached + non-interactive, or
+ * the user declined the confirm prompt). The host catches this, prints a friendly notice,
+ * and surfaces a structured `i18nprune.translate.identity_streak_abort` issue.
+ */
+declare class IdentityAbortError extends Error {
+    readonly command: string;
+    readonly target: string;
+    readonly threshold: number;
+    readonly count: number;
+    readonly path: string;
+    constructor(command: string, target: string, threshold: number, count: number, path: string);
+}
+
+/** Shared per-target counters for JSON payloads (CLI-compatible). */
+type GenerateTargetProgressSummary = {
+    sourceLeafCount?: number;
+    processedLeafCount?: number;
+    translatedLeafCount?: number;
+    /** Present on **`generate --resume`** rows (leaves written this run). */
+    updatedLeafCount?: number;
+    preserveCount?: number;
+    paritySkipCount?: number;
+    forced?: boolean;
+    durationMs?: number;
+    requestAttempts?: number;
+    requestRetries?: number;
+    requestSuccesses?: number;
+    requestFailures?: number;
+};
+type GenerateProgressEmit = (e: Omit<Extract<RunEvent, {
+    type: 'run.progress.generate';
+}>, 'op' | 'runId' | 'at'>) => void;
+/** Session progress API produced by the host (CLI: {@link createSessionProgress}). */
+type GenerateHostSession = {
+    readonly progress: {
+        tick(current: number, total: number, label: string, options?: TranslationTickProgressOptions): void;
+        pauseClock?(opts?: {
+            clearBar?: boolean;
+        }): void;
+        resumeClock?(): void;
+    };
+    finish(): void;
+    fail(): void;
+};
+/** Interactive choice when a target locale is only partially translated. */
+type GeneratePartialTargetChoice = 'skip' | 'fill_missing' | 'retranslate_all';
+type GenerateFinalizeSummaryInput = {
+    target: string;
+    englishName: string;
+    nativeName: string;
+    direction: 'ltr' | 'rtl';
+    targetPath: string;
+    leafCount: number;
+    /** When more than one segment file was written, finalize uses an aggregate summary line. */
+    wroteSegmentCount?: number;
+    dryRun?: boolean;
+    /** Pre-formatted locale line (e.g. `ar · Arabic · العربية · RTL`) when the host already resolved catalog labels. */
+    localeSubtitle?: string;
+};
+/**
+ * CLI / Worker wires TTY, prompts, progress bars, and JSON **`run.progress`** here — operation
+ * messages use the shared `RunEmitter` / `run.message` channel.
+ */
+type GenerateHostHooks = {
+    emitProgress: GenerateProgressEmit;
+    emit?: RunEmitter;
+    runId?: string;
+    createSession: () => GenerateHostSession;
+    createIdentityStreakGuard: (target: string, clock: {
+        pauseClock?: () => void;
+        resumeClock?: () => void;
+    }) => IdentityStreakGuard;
+    buildTickProgressRelay: (input: {
+        tick: GenerateHostSession['progress']['tick'];
+        target: string;
+        translationMeta: {
+            providerId: TranslationProviderId;
+            translationModel?: string;
+        };
+    }) => TranslationTickProgressFn;
+    /** Optional decorative newline before provider-fallback warning (CLI cursor lift). */
+    beforeProviderFallbackWarn?: () => void;
+    shouldSkipInteractivePrompts: () => boolean;
+    canAskInteractive: () => boolean;
+    promptFullRetranslate: () => Promise<boolean>;
+    /**
+     * Target locale exists but is incomplete (missing segment files and/or keys vs source).
+     * Host should offer skip, fill missing keys/segments, or full re-translate.
+     */
+    promptPartialTargetGenerate: (input: {
+        target: string;
+        missingSegmentPaths: string[];
+        missingKeyPaths: string[];
+    }) => Promise<GeneratePartialTargetChoice>;
+    printPreserveParityReport: (preserveCount: number, paritySkip: number) => void;
+    printFinalizeSummary: (input: GenerateFinalizeSummaryInput) => void;
+    onIdentityAbortNotice: (err: IdentityAbortError, opts: {
+        dryRun: boolean;
+    }) => void;
+};
+type ProviderAttemptReportJson = {
+    providerId: TranslationProviderId;
+    /** Legacy coarse bucket for CLI summaries (`rate_limited` / `network_error` / `non_retryable_error` / `success`). */
+    outcome: ProviderAttemptOutcome;
+    /**
+     * Fine-grained failure taxonomy from {@link classifyTranslateFailure} — present on **failed**
+     * attempts only (`translate-policy (shipped)` step 8, `--json` `targetResults[].providerAttempts[]`).
+     */
+    translateFailureOutcome?: TranslateFailureOutcome;
+};
+/** One row in {@link GenerateJsonPayload.targetResults}. */
+type GenerateTargetJsonRow = {
+    target: string;
+    status: 'written' | 'dry_run' | 'skipped_user_declined';
+    /** True when this target was written from a partial translate (policy / hook), not a full success. */
+    partial?: boolean;
+    /** Leaf values updated this run (**`generate --resume`** only). */
+    resumeUpdatedLeafCount?: number;
+    progress?: GenerateTargetProgressSummary;
+    sourceLeafCount?: number;
+    preserveCount?: number;
+    paritySkip?: number;
+    providerAttempts?: ProviderAttemptReportJson[];
+    winnerProviderId?: TranslationProviderId;
+    fallbackCount?: number;
+    markedForReview?: number;
+    paths?: {
+        /** Primary target locale path for single-file layouts. */
+        localeJson?: string;
+        /** Target locale segment paths for multi-file layouts (`locale_directory`). */
+        localeJsonPaths?: string[];
+    };
+    localeMetadata?: LocaleMetadataReport;
+};
+/** Payload inside `CliJsonEnvelope<'generate', …>` — stable JSON contract. */
+type GenerateJsonPayload = {
+    kind: 'generate';
+    providerId?: TranslationProviderId;
+    dryRun: boolean;
+    force: boolean;
+    targets: string[];
+    dynamicKeySites: number;
+    leavesProcessed: number;
+    targetResults: GenerateTargetJsonRow[];
+    /** Present when at least one target was written from a partial run (`translate.policy.onIncompleteRun`). */
+    partial?: boolean;
+    /** Hint for topping up leaves after a partial write (stable contract string). */
+    resumeHint?: string;
+    /** Sum of {@link GenerateTargetJsonRow.markedForReview} across targets written as partial in this run. */
+    markedForReview?: number;
+};
+/**
+ * Per-call options for {@link runGenerate}. **`targets`** must be resolved by the host (interactive
+ * prompt or **`--target`** parse). Use **`resume`** (+ optional **`all`**) for top-up runs.
+ */
+type GenerateRunOptions = {
+    readonly targets: readonly string[];
+    readonly dynamicKeySites: number;
+    readonly source?: string;
+    readonly provider?: string;
+    readonly workers?: number;
+    readonly force?: boolean;
+    readonly dryRun?: boolean;
+    readonly metadata?: boolean;
+    /** With **`--resume`**: confirm before processing targets. */
+    readonly ask?: boolean;
+    /**
+     * Top-up existing locale JSON (review-eligible leaves only). Requires existing **`&lt;target&gt;.json`**.
+     * Always combine with the **`--resume`** CLI flag — not a persisted config field.
+     */
+    readonly resume?: boolean;
+    /**
+     * CLI-built uncertain-prefix slice for resume eligibility; required when **`resume`** is true.
+     * Omitted on normal **`generate`** runs.
+     */
+    readonly resumeReference?: GenerateResumeRefContext;
+    /**
+     * When the CLI has already read the source JSON and emitted **`read_source`**, pass it here to avoid a
+     * second read and preserve **`run.progress`** ordering (**`read_source` → `resolve_targets`**).
+     */
+    readonly preloadedRaw?: unknown;
+};
+type GenerateRunResult = {
+    payload: GenerateJsonPayload;
+    /** Issues owned by generate (identity streak, empty-source warnings). Host merges discovery warnings. */
+    issues: Issue[];
+};
+
+/**
+ * Decision hooks for {@link runGenerate}. Pure type contracts: hosts implement them; core awaits
+ * each one at a defined consent point and the host's return value drives the run.
+ *
+ * Observability is intentionally **not** here — the existing `RunEmitter` / `RunEvent` surface
+ * carries `run.message`, `run.progress.generate`, `run.started`, `run.completed`, `run.summary`,
+ * and `run.failed`. New observability needs extend that union, not these hooks.
+ */
+
+/**
+ * Why **`runGenerate`** stopped before all source leaves were translated. Hosts use this to choose
+ * the right copy in the prompt and the right default action.
+ */
+type IncompleteRunReason = 
+/** Every provider in the chain was attempted; all failed with retryable errors (network / 5xx / rate-limit). */
+'provider_chain_exhausted'
+/** Mid-run hard failure (non-retryable error from a provider). Partial JSON is in memory. */
+ | 'partial_after_non_retryable'
+/** Every provider hit a rate-limit window and the run can't make forward progress without waiting. */
+ | 'rate_limit_persistent';
+/** Information passed to {@link GenerateRunHooks.onIncomplete}. */
+type IncompleteRunInfo = {
+    readonly target: string;
+    readonly reason: IncompleteRunReason;
+    readonly partial: TranslateRunPartialStats;
+    readonly successfulLeaves: number;
+    readonly failedLeaves: number;
+    readonly providerAttempts: readonly ProviderAttemptReportJson[];
+    readonly remainingProviderIds: readonly TranslationProviderId[];
+    readonly lastError?: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+/**
+ * Host's choice when {@link GenerateRunHooks.onIncomplete} is asked.
+ *
+ * - **`write_partial`** — keep what we have. **`metadata: true`** runs mark untranslated leaves
+ *   **`needsReview: true`** so a later **`generate --resume`** can top them up.
+ * - **`abort_no_write`** — re-throw the last error; no file is written; matches today's default.
+ * - **`retry_provider`** — try another provider id from {@link IncompleteRunInfo.remainingProviderIds}
+ *   with the partial state still in memory (no re-translation of completed leaves).
+ */
+type IncompleteRunDecision = {
+    readonly action: 'write_partial';
+} | {
+    readonly action: 'abort_no_write';
+} | {
+    readonly action: 'retry_provider';
+    readonly providerId: TranslationProviderId;
+};
+/** Information passed to {@link GenerateRunHooks.onHandoffPick}. */
+type HandoffOffer = {
+    readonly target: string;
+    readonly failedProviderId: TranslationProviderId;
+    readonly failureReason: 'rate_limited' | 'network_error' | 'non_retryable_error';
+    /** Classifier outcome for richer host copy (optional — legacy **`failureReason`** stays stable). */
+    readonly translateFailureOutcome?: TranslateFailureOutcome;
+    /** Config chain remainder (may be empty when **`routing: single`**). */
+    readonly remainingProviderIds: readonly TranslationProviderId[];
+    readonly partialStats: TranslateRunPartialStats;
+    /**
+     * Built-in catalogue pool eligible for rescue picks — **not** the same shape as **`remainingProviderIds`**
+     * (`translate-policy (shipped)` §8). Hosts render this list; **`onHandoffPick`** must return **`null`** (means
+     * “first **`eligibleHandoffRows`** entry”) or an id present in this list.
+     */
+    readonly eligibleHandoffRows: readonly HandoffEligibilityRow[];
+};
+/**
+ * Decision hooks for **`runGenerate`**. Each is optional; omitting one means "use core's default
+ * for that consent point" (see **`translate.policy`** merge in core).
+ *
+ * Hosts that need full UX (CLI prompt, web modal, etc.) supply these. Headless hosts (CI, Worker,
+ * SDK) often omit **`onIncomplete`** so **`onIncompleteRun: 'confirm'`** defaults to **`write_partial`**
+ * in core, or set **`onIncompleteRun: 'write'`** / **`'discard'`** for policy-only behavior.
+ */
+type GenerateRunHooks = {
+    /**
+     * Invoked only when **`translate.policy.onIncompleteRun`** is **`'confirm'`** and a target stops
+     * before every leaf finished. Return **`write_partial`** to finalize and write in-memory JSON, or
+     * **`abort_no_write`** to rethrow the last error. **`retry_provider`** is reserved (throws if returned).
+     * For **`onIncompleteRun: 'write'`** or **`'discard'`**, core does not call **`onIncomplete`**.
+     */
+    readonly onIncomplete?: (info: IncompleteRunInfo) => Promise<IncompleteRunDecision>;
+    /**
+     * Mid-run picker for **`prompt`** verbs (`quota_exceeded · prompt`, **`onAuthFailure: prompt`**, …).
+     * Return **`null`** to accept the default (**first **`eligibleHandoffRows`** row**). Any non-null id
+     * must appear in **`offer.eligibleHandoffRows`**.
+     */
+    readonly onHandoffPick?: (offer: HandoffOffer) => Promise<TranslationProviderId | null>;
+};
+
+/**
+ * Public **`runGenerate`** — project-scoped generate: read source locale, walk targets, run per-provider
+ * translate+normalize, write files. Host supplies TTY / prompts / progress via {@link GenerateHostHooks}.
+ */
+
+declare function runGenerate(ctx: CoreContext, opts: GenerateRunOptions, host: GenerateHostHooks, hooks?: GenerateRunHooks): Promise<GenerateRunResult>;
+
+/**
+ * Stable human-readable finalize lines for generate (locale identity + write summary).
+ * Hosts map {@link GenerateFinalizeSummaryInput.localeSubtitle} from catalog metadata; core owns wording only.
+ */
+declare function formatGenerateFinalizeSummaryLines(input: GenerateFinalizeSummaryInput & {
+    localeSubtitle: string;
+}): string[];
+
+/**
+ * Resolve English/native labels and layout direction for a generate target.
+ *
+ * @remarks Pure — catalog + heuristics only; no flags or sidecar files.
+ */
+declare function resolveLocaleDirection(targetCode: string, catalogDirection?: unknown): 'ltr' | 'rtl';
+/**
+ * @param targetCode - BCP-47-ish locale code being generated.
+ * @param catalogEntry - Row from `languages.json` when the code is catalog-backed.
+ */
+declare function resolveGenerateLocaleDisplay(targetCode: string, catalogEntry?: TranslateTargetLanguage): GenerateLocaleDisplay;
+
+/**
+ * Walk source leaves: preserve / parity rules, then translate or copy into `working` object.
+ * Callers supply `Translator`, policies, and progress hooks (CLI wires TTY / `run.progress` here).
+ */
+declare function buildTranslatedLocaleFromSourceLeaves(input: {
+    sourceLeaves: readonly StringLeaf[];
+    working: unknown;
+    existingRaw: unknown | null;
+    preserve?: PreservePolicy;
+    parity?: ParityPolicy;
+    dryRun: boolean;
+    force: boolean;
+    provider: Translator;
+    /** When true, write `{ value, status, … }` leaves using merged {@link translateLeaf} metadata. */
+    persistStructuredLeafMetadata: boolean;
+    providerId: TranslationProviderId;
+    /** BCP-47-ish source tag passed to **`translateLeaf`** (default **`en`**). */
+    sourceLang?: string;
+    targetLang: string;
+    /** Per-run L1 memo; omitted when host bypassed cache (`--no-cache`). */
+    translationCache?: GenerateTranslateCache;
+    /** Max in-flight **`translateLeaf`** calls; **1** keeps serial semantics (default). */
+    maxParallelTranslates?: number;
+    rateLimit?: TranslateStartRateLimit;
+    tickProgress: TranslationTickProgressFn;
+    onTranslatedLeaf?: (sourceText: string, translatedText: string, path: string) => Promise<void> | void;
+}): Promise<{
+    working: unknown;
+    preserveCount: number;
+    paritySkip: number;
+    /** Leaf paths whose source **value** was whitespace-only — copied without calling the translator. */
+    emptySourceLeafPaths: readonly string[];
+    translateStats: TranslateRunPartialStats;
+    /** Count of translated leaves classified as review-needed by policy/meta pipeline. */
+    markedForReview: number;
+}>;
+/** Re-scan paths that still exist after deletes (cleanup helper). */
+declare function localeJsonHasKeyPath(data: unknown, keyPath: string): boolean;
+/**
+ * **`generate --resume`**: walk review leaves, translate candidates that still match source, update JSON.
+ */
+declare function translateResumeCandidateLeaves(input: {
+    tLeaves: readonly TranslationSurfaceLeaf[];
+    next: unknown;
+    sourceMap: Map<string, string>;
+    refCtx: GenerateResumeRefContext;
+    eff: EffectiveReferenceConfig;
+    preserve?: PreservePolicy;
+    parity?: ParityPolicy;
+    provider: Translator;
+    providerId: TranslationProviderId;
+    /** BCP-47-ish source tag passed to **`translateLeaf`** (default **`en`**). */
+    sourceLang?: string;
+    persistStructuredLeafMetadata: boolean;
+    target: string;
+    dryRun: boolean;
+    maxParallelTranslates?: number;
+    rateLimit?: TranslateStartRateLimit;
+    /** Per-run L1 memo; omitted when host bypassed cache (`--no-cache`). */
+    translationCache?: GenerateTranslateCache;
+    tickProgress: TranslationTickProgressFn;
+    onTranslatedLeaf?: (sourceText: string, translatedText: string, path: string) => Promise<void> | void;
+}): Promise<{
+    next: unknown;
+    changed: number;
+    translateStats: TranslateRunPartialStats;
+    markedForReview: number;
+}>;
+
+/**
+ * Generate: translate source leaves into a working locale object, then apply structured-metadata /
+ * legacy normalization (same ordering as CLI `executeGenerate`).
+ */
+declare function translateAndNormalizeGenerateLocale(input: {
+    sourceLeaves: readonly StringLeaf[];
+    working: unknown;
+    existingRaw: unknown | null;
+    preserve?: PreservePolicy;
+    parity?: ParityPolicy;
+    dryRun: boolean;
+    force: boolean;
+    provider: Translator;
+    providerId: TranslationProviderId;
+    /** BCP-47-ish source tag passed to **`translateLeaf`** (default **`en`**). */
+    sourceLang?: string;
+    targetLang: string;
+    sourceMap: Map<string, string>;
+    tickProgress: TranslationTickProgressFn;
+    onTranslatedLeaf?: (sourceText: string, translatedText: string, path: string) => Promise<void> | void;
+    localeLeafResolve: ResolveLocaleLeafModeInput;
+    /** Max in-flight **`translateLeaf`** calls during generate (default **1**). */
+    maxParallelTranslates?: number;
+    /** Optional translate request pacing limits (rpm/rps/intervalMs). */
+    rateLimit?: TranslateStartRateLimit;
+    /** Per-run L1 memo; omitted when host bypassed cache (`--no-cache`). */
+    translationCache?: GenerateTranslateCache;
+}): Promise<{
+    preserveCount: number;
+    paritySkip: number;
+    /** Leaves whose source string value was whitespace-only (**`dryRun`** counts them too). */
+    emptySourceLeafCount: number;
+    next: unknown;
+    report: LocaleMetadataReport;
+    modeDecision: ReturnType<typeof resolveLocaleLeafMode>;
+    issues: Issue[];
+    translateStats: TranslateRunPartialStats;
+    markedForReview: number;
+}>;
+
+/**
+ * Thrown when **`translateLeaf`** fails mid-run while the translator pool / serial loop has already
+ * committed earlier leaf updates into **`partialLocaleJson`**. Callers (currently **`runGenerate`** and
+ * **`generate --resume`**) catch this so a fallback provider can resume without re-translating completed paths.
+ */
+declare class TranslateRunInterruptedError extends Error {
+    readonly name = "TranslateRunInterruptedError";
+    readonly partialLocaleJson: unknown;
+    readonly translateStats: TranslateRunPartialStats;
+    constructor(init: {
+        /** Usually the backend rejection that stopped the pool / serial loop. */
+        cause: unknown;
+        partialLocaleJson: unknown;
+        translateStats: TranslateRunPartialStats;
+        message?: string;
+    });
+}
+
+/** Whether this leaf would be considered for **`generate --resume`**. */
+declare function isResumeCandidateLeaf(input: GenerateResumeCandidateLeafInput): boolean;
+
+/**
+ * Detects when a locale string still matches the **source** string closely enough that a
+ * **`generate --resume`** pass should treat it as a stale / untranslated copy (strict equality plus
+ * light normalization).
+ */
+declare function leafMatchesSourceForResume(leafValue: string, sourceValue: string): boolean;
+
+export { CoreContext, type GenerateHostHooks, type GenerateJsonPayload, type GenerateRunHooks, type GenerateRunOptions, type GenerateRunResult, type GenerateTargetJsonRow, type GenerateTargetProgressSummary, HandoffEligibilityRow, type HandoffOffer, type IncompleteRunDecision, type IncompleteRunInfo, type IncompleteRunReason, TranslateRunInterruptedError, TranslateRunPartialStats, buildTranslatedLocaleFromSourceLeaves, createCoreContext, formatGenerateFinalizeSummaryLines, isResumeCandidateLeaf, leafMatchesSourceForResume, localeJsonHasKeyPath, resolveGenerateLocaleDisplay, resolveLocaleDirection, runGenerate, translateAndNormalizeGenerateLocale, translateContextFromCore, translateResumeCandidateLeaves };