@i18nprune/core 0.1.0

package/dist/humanEmit-ygNlYX-S.d.ts

@@ -0,0 +1,79 @@
+import { D as DynamicKeySite } from './index-DdjljwMj.js';
+import { I as Issue } from './index-X50E1FIX.js';
+import { L as LocaleMetadataReport } from './index-DLwTogCo.js';
+import { R as RunEmitter, S as SyncProgressEvent } from './index-BgG01AKL.js';
+import { S as SourcePlaceholderLeaf, L as LocalePlaceholderLeaf } from './index-DeIw-cZd.js';
+
+/** Counts for human sync logging (**merge + prune** vs source template only). */
+type SyncHumanLeafSummary = {
+    /** Source paths that had no existing leaf in the target before sync. */
+    hydratedFromSource: number;
+    /** Source paths that already had a readable leaf before merge+prune. */
+    preservedExistingLeaves: number;
+    /** Previously present string-leaf dotted paths outside the template (removed to match source shape). */
+    prunedExtraLeaves: number;
+};
+
+type SyncFileLine = {
+    path: string;
+    changed: boolean;
+};
+/**
+ * Payload shape for `i18nprune sync --json`.
+ * Additive fields may appear in future versions.
+ */
+type SyncJsonOutput = {
+    kind: 'sync';
+    sourcePath: string;
+    localesDir: string;
+    targetFiles: number;
+    writtenFiles: number;
+    dynamicKeySites: number;
+    dryRun: boolean;
+    files: SyncFileLine[];
+    localeMetadataReports?: Record<string, LocaleMetadataReport>;
+};
+type SyncRunOptions = {
+    /** Report only; do not write locale files. */
+    dryRun?: boolean;
+    /** Comma-separated locale basenames, or `all` (default: all non-source locales). */
+    target?: string;
+    /** Write/repair structured locale leaves (`{ value, status, confidence, needsReview, source }`). */
+    metadata?: boolean;
+    /** Force reset structured leaf metadata to plain string values. */
+    stripMetadata?: boolean;
+};
+type SyncHostHooks = {
+    emit?: RunEmitter;
+    runId?: string;
+    emitProgress: (e: Omit<Extract<SyncProgressEvent, {
+        type: 'run.progress.sync';
+    }>, 'op' | 'runId' | 'at'>) => void;
+};
+type SyncRunResult = {
+    payload: SyncJsonOutput;
+    issues: Issue[];
+    fileLines: SyncFileLine[];
+    targets: string[];
+    updated: number;
+    dynamicSites: DynamicKeySite[];
+    keyObservationsCount: number;
+    /** Requested locale codes with no matching file under `localesDir` (human-mode warning). */
+    missingLocaleCodes: string[];
+    /** Per-locale leaf stats for human stderr (not part of `--json`). */
+    humanLeafSummaryByLocaleFile: Record<string, SyncHumanLeafSummary>;
+    /** Source placeholder leaves skipped to avoid copying scaffold sentinels into target locales. */
+    sourcePlaceholderLeaves: SourcePlaceholderLeaf[];
+    /** Target placeholder leaves observed before sync applies its source-shape plan. */
+    targetPlaceholderLeaves: LocalePlaceholderLeaf[];
+};
+
+type SyncLocaleDisplayGroup = {
+    localeCode: string;
+    reportKeys: string[];
+    fileLines: SyncFileLine[];
+    changedCount: number;
+    summaries: SyncHumanLeafSummary[];
+};
+
+export type { SyncHostHooks as S, SyncRunResult as a, SyncRunOptions as b, SyncHumanLeafSummary as c, SyncFileLine as d, SyncJsonOutput as e, SyncLocaleDisplayGroup as f };

package/dist/index-BQuLEQ9b.d.ts

@@ -0,0 +1,7 @@
+/** One string leaf in a JSON tree (`a[0].b` style paths). */
+type StringLeaf = {
+    path: string;
+    value: string;
+};
+
+export type { StringLeaf as S };

package/dist/index-B_ow_Xvr.d.ts

@@ -0,0 +1,97 @@
+import { a as LocaleLeafMode, S as StructuredLocaleLeaf } from './index-DLwTogCo.js';
+import { T as TranslationProviderId } from './providers-0uMEfT6q.js';
+
+type ApplyLocaleMetadataModeInput = {
+    localeJson: unknown;
+    sourceMap: Map<string, string>;
+    mode: LocaleLeafMode;
+    sampleLimit?: number;
+};
+type ResolveLocaleLeafModeInput = {
+    configMode?: LocaleLeafMode;
+    metadataFlag?: boolean;
+    stripMetadataFlag?: boolean;
+};
+
+/**
+ * Optional per-leaf fields merged into a structured locale leaf (`{ value, … }`).
+ * `value` always comes from {@link TranslationResult.text}; this patch is everything else.
+ */
+type TranslationLeafMetaPatch = Partial<Pick<StructuredLocaleLeaf, 'status' | 'confidence' | 'needsReview' | 'needsTranslationAgain' | 'source'>>;
+/**
+ * Rich provider response (before heuristic merge). `leafMeta` may be partial or omitted.
+ */
+type TranslationProviderYield = {
+    readonly text: string;
+    readonly leafMeta?: TranslationLeafMetaPatch;
+};
+/**
+ * Final per-leaf metadata after provider + heuristic merge (`translateLeaf`).
+ * All fields are always set so hosts can rely on them without optional chaining.
+ */
+type TranslationLeafMeta = {
+    status: string;
+    confidence: number | null;
+    needsReview: boolean;
+    needsTranslationAgain: boolean;
+    source: string;
+};
+/**
+ * Post-translation routing signal for a single leaf.
+ *
+ * - `'translated'` — leaf is final; downstream consumers treat it as done.
+ * - `'review'` — leaf needs human or workflow attention before it can be considered
+ *   complete. The persisted marker is `needsReview: true` on the structured leaf
+ *   (no separate key — see `translate-policy (shipped)` §5).
+ *
+ * The decision is the source of truth; the structured-leaf `needsReview` flag mirrors it.
+ * `finalizeTranslationLeafMeta` enforces the mirror.
+ */
+type LeafDecision = 'translated' | 'review';
+/**
+ * Output of {@link translateLeaf}: final string plus **merged** metadata (provider + heuristic).
+ * **`leafMeta`** is always fully populated. The CLI only **persists** structured locale JSON when the
+ * user passes **`--metadata`**; core does not strip metadata based on that flag.
+ */
+type TranslationResult = {
+    readonly text: string;
+    readonly leafMeta: TranslationLeafMeta;
+    /** Optional policy decision; `review` promotes attention workflows downstream. */
+    readonly decision?: LeafDecision;
+    /** Runtime-only transport stats (not persisted to locale JSON). */
+    readonly runtime?: {
+        attempts: number;
+        retries: number;
+    };
+};
+/** Context for heuristic metadata when a provider returns no scores. */
+type HeuristicLeafMetaInput = {
+    readonly sourceText: string;
+    readonly translatedText: string;
+    readonly providerId: TranslationProviderId;
+};
+
+/** HTTP/API backend: one string in, one string out (placeholders handled by `Translator`). */
+type TranslateRequest = {
+    text: string;
+    sourceLang: string;
+    targetLang: string;
+};
+/** Defaults: 3 tries; delays 400ms / 900ms after 1st and 2nd failure. */
+type TranslatorRetryOptions = {
+    maxAttempts: number;
+    delaysMs: number[];
+};
+type Translator = {
+    translate(text: string, sourceLang: string, targetLang: string): Promise<string | TranslationProviderYield | TranslationResult>;
+};
+
+type TranslateTargetLanguage = {
+    code: string;
+    english: string;
+    native: string;
+    direction: 'ltr' | 'rtl';
+    [extra: string]: unknown;
+};
+
+export type { ApplyLocaleMetadataModeInput as A, HeuristicLeafMetaInput as H, LeafDecision as L, ResolveLocaleLeafModeInput as R, TranslationResult as T, TranslationLeafMeta as a, TranslateTargetLanguage as b, Translator as c, TranslateRequest as d, TranslationLeafMetaPatch as e, TranslationProviderYield as f, TranslatorRetryOptions as g };

package/dist/index-BgG01AKL.d.ts

@@ -0,0 +1,287 @@
+import { I as Issue } from './index-X50E1FIX.js';
+import { T as TranslationProviderId } from './providers-0uMEfT6q.js';
+
+/**
+ * Core share cache + worker envelope types (disk `share.json` + worker JSON).
+ * @see maintainer/systems/share.md
+ */
+
+type ShareKind = 'project' | 'report';
+/** On-disk `share.json` (v1) beside `files.json` / `analysis.json`. */
+type ShareJsonFile = {
+    version: 1;
+    entries: ShareCacheEntry[];
+};
+type ShareLinks = {
+    web?: string;
+    report?: string;
+    worker?: string;
+};
+/** One recorded upload from this machine (local cache metadata). */
+type ShareCacheEntry = {
+    kind: ShareKind;
+    workerBaseUrl: string;
+    workerProjectId?: string;
+    workerReportId?: string;
+    payloadContentHash: string;
+    configHash?: string;
+    /** Tracked-files epoch from `files.json` when the project snapshot was last shared (skip zip rebuild). */
+    inputFilesEpoch?: string;
+    byteSize: number;
+    uploadedAt: string;
+    lastUsedAt: string;
+    links: ShareLinks;
+};
+type ShareJsonHealKind = 'missing_file' | 'invalid_json' | 'oversized_file' | 'version_reset' | 'entries_sanitized' | 'duplicates_merged';
+type ShareJsonHealReport = {
+    /** True when any corrective action was applied (including initializing an empty file). */
+    repaired: boolean;
+    actions: ShareJsonHealKind[];
+    /** Human-readable detail lines for hosts (CLI may log once). */
+    details: string[];
+    /** Set when the previous `share.json` was copied under `share.bak/` before replace. */
+    backupBakPath?: string;
+};
+type LoadShareJsonResult = {
+    file: ShareJsonFile;
+    heal: ShareJsonHealReport;
+    issues: Issue[];
+};
+/** Parsed worker JSON envelope (subset used by share / worker hosts). */
+type WorkerShareEnvelope = {
+    success: boolean;
+    code?: string;
+    data: unknown;
+    errors: Array<{
+        code: string;
+        message: string;
+    }>;
+    warnings?: Array<{
+        code: string;
+        message: string;
+    }>;
+};
+
+/**
+ * Prepared project snapshot manifest (zip not included — described by hashes + counts).
+ */
+type ShareProjectManifest = {
+    kind: 'project';
+    fileCount: number;
+    textFileCount: number;
+    byteSize: number;
+    /** Distinct first path segments (cap ~20) for human logs. */
+    topLevelPrefixes: readonly string[];
+    /** Short label describing built-in exclude rules (see `shouldSkipPathForShareZip`). */
+    appliedZipIgnoresLabel: string;
+    payloadContentHash: string;
+    configHash: string;
+    detectedConfigRelPath: string | null;
+};
+/** Prepared report payload manifest (validated `ProjectReportDocument` JSON). */
+type ShareReportManifest = {
+    kind: 'report';
+    byteSize: number;
+    payloadContentHash: string;
+    schemaVersion: number;
+    toolVersion: string;
+    generatedAt: string;
+};
+type ShareManifest = ShareProjectManifest | ShareReportManifest;
+
+/**
+ * Known operation identifiers for `run.*` events.
+ *
+ * Note: this is intentionally small while the event contract is being threaded
+ * through operations. Expand as each operation adopts `run.*`.
+ */
+type OperationId = 'generate' | 'sync' | 'validate' | 'quality' | 'doctor' | 'report' | 'review' | 'missing' | 'cleanup' | 'locales-dynamic' | 'share';
+type RunEventBase = {
+    /** Operation identifier (matches `CliJsonEnvelope.kind`). */
+    op: OperationId;
+    /** Optional run correlation id (host-provided). */
+    runId?: string;
+};
+type RunStartedEvent = RunEventBase & {
+    type: 'run.started';
+    at: number;
+};
+type GenerateCounts = {
+    targets: number;
+    leaves: number;
+    dynamicKeySites: number;
+};
+type SyncCounts = {
+    targets: number;
+    written: number;
+    dynamicKeySites: number;
+};
+type ValidateCounts = {
+    missing: number;
+    dynamic: number;
+    keyObservations: number;
+};
+type QualityCounts = {
+    total: number;
+    dynamicKeySites: number;
+};
+type DoctorCounts = {
+    findings: number;
+};
+type ReportCounts = {
+    filesScanned?: number;
+    missing?: number;
+    dynamic?: number;
+    keyObservations?: number;
+};
+type ReviewCounts = {
+    locales: number;
+    dynamicKeySites: number;
+};
+type MissingCounts = {
+    pathsAdded: number;
+    targets?: number;
+    skippedTargets?: number;
+};
+type CleanupCounts = {
+    wouldRemove: number;
+    dynamicKeySites: number;
+};
+type LocalesDynamicCounts = {
+    dynamicKeySites: number;
+    shown: number;
+};
+type ShareCounts = {
+    fileCount: number;
+    zipBytes: number;
+};
+type RunCountsByOperation = {
+    generate: GenerateCounts;
+    sync: SyncCounts;
+    validate: ValidateCounts;
+    quality: QualityCounts;
+    doctor: DoctorCounts;
+    report: ReportCounts;
+    review: ReviewCounts;
+    missing: MissingCounts;
+    cleanup: CleanupCounts;
+    'locales-dynamic': LocalesDynamicCounts;
+    share: ShareCounts;
+};
+type RunCompletedEventFor<T extends OperationId> = Omit<RunEventBase, 'op'> & {
+    op: T;
+    type: 'run.completed';
+    at: number;
+    ok: boolean;
+};
+type RunCompletedEvent = {
+    [K in OperationId]: RunCompletedEventFor<K>;
+}[OperationId];
+type RunFailedEvent = RunEventBase & {
+    type: 'run.failed';
+    at: number;
+    error: {
+        /** Stable-ish error identifier for clients (not necessarily an issue code). */
+        name: string;
+        message: string;
+        recoverable: false;
+    };
+};
+type RunWarningEvent = RunEventBase & {
+    type: 'run.warning';
+    at: number;
+    issue: Issue;
+};
+type RunErrorEvent = RunEventBase & {
+    type: 'run.error';
+    at: number;
+    issue: Issue;
+    /** When true, operation may continue and still complete successfully. */
+    recoverable: boolean;
+};
+type RunMessageLevel = 'detail' | 'info' | 'notice' | 'tip' | 'warn';
+type RunMessageChannel = 'default' | 'cache' | 'verbose';
+type RunMessageEvent = RunEventBase & {
+    type: 'run.message';
+    at: number;
+    level: RunMessageLevel;
+    channel?: RunMessageChannel;
+    message: string;
+    target?: string;
+    path?: string;
+    data?: Record<string, string | number | boolean | null>;
+};
+type RunShareManifestEvent = RunEventBase & {
+    op: 'share';
+    type: 'run.share.manifest';
+    at: number;
+    manifest: ShareManifest;
+};
+type RunShareSkippedEvent = RunEventBase & {
+    op: 'share';
+    type: 'run.share.skipped';
+    at: number;
+    reason: string;
+    links: ShareLinks;
+    workerIds: {
+        projectId?: string;
+        reportId?: string;
+    };
+};
+type RunShareUploadedEvent = RunEventBase & {
+    op: 'share';
+    type: 'run.share.uploaded';
+    at: number;
+    kind: 'project' | 'report';
+    workerProjectId?: string;
+    workerReportId?: string;
+    byteSize: number;
+};
+type RunShareLinksEvent = RunEventBase & {
+    op: 'share';
+    type: 'run.share.links';
+    at: number;
+    links: ShareLinks;
+};
+type ProgressEvent<T extends OperationId> = RunEventBase & {
+    type: `run.progress.${T}`;
+    at: number;
+    current?: number;
+    total?: number;
+    label?: string;
+};
+/** Not all operations emit progress events; only ones with meaningful streaming progress should. */
+type GeneratePhase = 'scan_dynamic_sites' | 'read_source' | 'resolve_targets' | 'build_target' | 'translate' | 'write_files' | 'done';
+type SyncPhase = 'scan_dynamic_sites' | 'read_source' | 'resolve_targets' | 'build_target' | 'merge' | 'prune' | 'write_files' | 'done';
+type ValidatePhase = 'scan_sources' | 'extract_keys' | 'read_source' | 'compare' | 'done';
+/** Per-operation progress payloads. */
+type GenerateProgressEvent = ProgressEvent<'generate'> & {
+    target?: string;
+    phase: GeneratePhase;
+    /** Active translation backend — **non-secret** (for logs / `--json` consumers). */
+    providerId?: TranslationProviderId;
+    /** e.g. LLM model id when using an AI provider — **never** API keys or tokens. */
+    translationModel?: string;
+};
+type SyncProgressEvent = ProgressEvent<'sync'> & {
+    target?: string;
+    phase: SyncPhase;
+};
+type ValidateProgressEvent = ProgressEvent<'validate'> & {
+    phase: ValidatePhase;
+};
+type RunSummaryEventFor<T extends OperationId> = Omit<RunEventBase, 'op'> & {
+    op: T;
+    type: 'run.summary';
+    at: number;
+    ok: boolean;
+    issueCount: number;
+    counts: RunCountsByOperation[T];
+};
+type RunSummaryEvent = {
+    [K in OperationId]: RunSummaryEventFor<K>;
+}[OperationId];
+type RunEvent = RunStartedEvent | RunWarningEvent | RunErrorEvent | RunMessageEvent | RunFailedEvent | RunCompletedEvent | RunSummaryEvent | GenerateProgressEvent | SyncProgressEvent | ValidateProgressEvent | RunShareManifestEvent | RunShareSkippedEvent | RunShareUploadedEvent | RunShareLinksEvent;
+type RunEmitter = (event: RunEvent) => void;
+
+export type { RunStartedEvent as A, RunSummaryEvent as B, CleanupCounts as C, DoctorCounts as D, RunWarningEvent as E, ShareCounts as F, GenerateCounts as G, ShareJsonHealKind as H, SyncCounts as I, SyncPhase as J, ValidatePhase as K, LoadShareJsonResult as L, MissingCounts as M, ValidateProgressEvent as N, OperationId as O, ProgressEvent as P, QualityCounts as Q, RunEmitter as R, SyncProgressEvent as S, ValidateCounts as V, WorkerShareEnvelope as W, RunEvent as a, ShareProjectManifest as b, ShareReportManifest as c, ShareKind as d, ShareCacheEntry as e, ShareManifest as f, ShareLinks as g, ShareJsonFile as h, ShareJsonHealReport as i, GeneratePhase as j, GenerateProgressEvent as k, LocalesDynamicCounts as l, ReportCounts as m, ReviewCounts as n, RunCompletedEvent as o, RunCountsByOperation as p, RunErrorEvent as q, RunEventBase as r, RunFailedEvent as s, RunMessageChannel as t, RunMessageEvent as u, RunMessageLevel as v, RunShareLinksEvent as w, RunShareManifestEvent as x, RunShareSkippedEvent as y, RunShareUploadedEvent as z };

package/dist/index-CIzZl4W8.d.ts

@@ -0,0 +1,124 @@
+import { I as Issue } from './index-X50E1FIX.js';
+import { R as RunEmitter } from './index-BgG01AKL.js';
+
+type MissingTargetKind = 'source' | 'locale';
+/**
+ * Payload shape for `i18nprune missing --json`.
+ * Additive fields may appear in future versions.
+ */
+type MissingJsonOutput = {
+    kind: 'missing';
+    targetPath: string;
+    targetPaths?: string[];
+    targetKind: MissingTargetKind;
+    pathsAdded: number;
+    shown: number;
+    top: number | null;
+    full: boolean;
+    paths: string[];
+    dryRun: boolean;
+    skippedNotInScan: string[];
+    targets: MissingJsonTarget[];
+    skippedTargets: MissingSkippedTarget[];
+    placeholderLeaves: MissingPlaceholderLeafList;
+};
+type MissingRunOptions = {
+    /** Locale basename(s) under `localesDir`, or `all`; omit = source locale file. */
+    target?: string;
+    dryRun?: boolean;
+    /** Max placeholder leaves to include in JSON listings; default 10. Ignored when `full` is true. */
+    top?: number;
+    /** JSON listings include every placeholder leaf (overrides `top`). */
+    full?: boolean;
+};
+type MissingTargetState = {
+    targetPath: string;
+    targetKind: MissingTargetKind;
+    localeJson: unknown;
+    localeText: string;
+    selectedLocaleCode?: string;
+    selectedLocaleEnglishName?: string;
+    targetDisplayPath?: string;
+};
+type MissingSkippedTarget = {
+    localeCode: string;
+    targetPath: string;
+    reason: 'not_found' | 'source_locale';
+    suggestions?: string[];
+};
+type MissingSegmentWrite = {
+    targetPath: string;
+    relativePath: string;
+    paths: string[];
+};
+type MissingTargetPlan = {
+    target: MissingTargetState;
+    toAdd: string[];
+    skippedNotInScan: string[];
+    /** Per-segment file writes (multi-segment layouts). */
+    writePlan: MissingSegmentWrite[];
+};
+type MissingJsonTarget = {
+    targetPath: string;
+    targetPaths?: string[];
+    targetKind: MissingTargetKind;
+    selectedLocaleCode?: string;
+    pathsAdded: number;
+    paths: string[];
+    skippedNotInScan: string[];
+};
+type MissingPlaceholderLeaf = {
+    localeRole: MissingTargetKind;
+    localeCode: string;
+    file: string;
+    path: string;
+    value: string;
+    line: number | null;
+    location: string;
+};
+type MissingPlaceholderLeafList = {
+    count: number;
+    shown: number;
+    top: number | null;
+    full: boolean;
+    leaves: MissingPlaceholderLeaf[];
+};
+type MissingHostHooks = {
+    emit?: RunEmitter;
+    runId?: string;
+};
+type MissingRunResult = {
+    payload: MissingJsonOutput;
+    issues: Issue[];
+    targets: MissingTargetPlan[];
+    skippedTargets: MissingSkippedTarget[];
+    /** Aggregate across planned targets, preserved for simple callers. */
+    toAdd: string[];
+    skippedNotInScan: string[];
+    dynamicSites: number;
+    keyObservationsCount: number;
+    placeholderLeaves: MissingPlaceholderLeaf[];
+};
+type MissingWriteInput = {
+    targetPath: string;
+    localeJson: unknown;
+    localeCode?: string;
+    paths: readonly string[];
+    placeholder: string;
+    writePlan?: MissingSegmentWrite[];
+};
+
+type ResolveMissingPathsPlanInput = {
+    /** Target locale JSON object used to detect already-existing string leaves. */
+    localeJson?: unknown;
+    /** Merged leaves for multi-segment locales (preferred over `localeJson` when set). */
+    localeLeaves?: ReadonlyArray<{
+        path: string;
+    }>;
+    /** All resolved literal keys seen in the current project scan. */
+    resolvedKeys: ReadonlySet<string>;
+    /** Optional `missing` entries from a prior validate JSON report. */
+    reportMissingPaths?: readonly string[];
+};
+
+export type { MissingHostHooks as M, ResolveMissingPathsPlanInput as R, MissingPlaceholderLeaf as a, MissingTargetPlan as b, MissingRunOptions as c, MissingRunResult as d, MissingWriteInput as e, MissingSegmentWrite as f, MissingJsonOutput as g, MissingJsonTarget as h, MissingPlaceholderLeafList as i, MissingSkippedTarget as j, MissingTargetKind as k, MissingTargetState as l };

package/dist/index-Csm1w7XD.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Rich observations for literal and template-resolved translation keys (keySites phase).
+ * Heuristic dynamic sites stay under `types/extractor/dynamic`.
+ */
+/** Where an observation was found (merged scan may omit `filePath`). */
+type SourceSpan = {
+    filePath?: string;
+    line: number;
+    column?: number;
+    functionName?: string;
+    /** True when the translation call spans multiple lines. */
+    isMultilineCall?: boolean;
+    /** UTF-16 offset of the translation call in the file (for comment filtering). */
+    charOffset?: number;
+};
+/** One step replacing `${identifier}` using `constMap` during template resolution. */
+type ConstSubstitutionStep = {
+    identifier: string;
+    value: string;
+};
+/** Optional cross-link to a heuristic dynamic site (same file:line when matched). */
+type DynamicKeyRef = {
+    filePath?: string;
+    line?: number;
+};
+type LiteralKeyObservation = {
+    kind: 'literal';
+    resolvedKey: string;
+    /** Inner string as matched, e.g. `a.b.c` */
+    raw: string;
+    span: SourceSpan;
+    dynamicRef?: DynamicKeyRef;
+};
+type TemplateResolvedKeyObservation = {
+    kind: 'template_resolved';
+    resolvedKey: string;
+    templateRaw: string;
+    substitutions: ConstSubstitutionStep[];
+    span: SourceSpan;
+    dynamicRef?: DynamicKeyRef;
+};
+type TemplatePartialKeyObservation = {
+    kind: 'template_partial';
+    templateRaw: string;
+    substitutions: ConstSubstitutionStep[];
+    /** `${name}` segments still unresolved after constMap */
+    unresolvedPlaceholders: string[];
+    span: SourceSpan;
+    dynamicRef?: DynamicKeyRef;
+    /**
+     * Longest static key path prefix before the first unresolvable `${…}` (see dynamic rebuild),
+     * when it contains a dot segment; used for uncertain-key protection.
+     */
+    uncertainPrefix?: string;
+};
+type KeyObservation = LiteralKeyObservation | TemplateResolvedKeyObservation | TemplatePartialKeyObservation;
+
+export type { ConstSubstitutionStep as C, DynamicKeyRef as D, KeyObservation as K, LiteralKeyObservation as L, SourceSpan as S, TemplatePartialKeyObservation as T, TemplateResolvedKeyObservation as a };

package/dist/index-DLwTogCo.d.ts

@@ -0,0 +1,43 @@
+type LocaleLeafMode = 'legacy_string' | 'structured';
+
+type StructuredLocaleLeaf = {
+    value: string;
+    status?: string;
+    confidence?: number | null;
+    needsReview?: boolean;
+    needsTranslationAgain?: boolean;
+    source?: string;
+};
+
+type LocaleMetadataRepairReason = 'legacy_string_promoted' | 'non_object_replaced' | 'missing_value' | 'invalid_status' | 'invalid_confidence' | 'invalid_needs_review' | 'invalid_needs_translation_again' | 'invalid_source' | 'canonical_metadata_materialized';
+type LocaleMetadataPathChange = {
+    path: string;
+    reason: LocaleMetadataRepairReason;
+};
+type LocaleLeafRuntimeKind = 'missing' | 'legacy_string' | 'structured_valid' | 'structured_corrupt' | 'other';
+type LocaleLeafDecisionAction = 'unchanged' | 'hydrated_missing' | 'promoted_legacy' | 'repaired_corrupt' | 'stripped_structured';
+type LocaleMetadataLeafDecision = {
+    path: string;
+    sourceValue: string;
+    beforeKind: LocaleLeafRuntimeKind;
+    afterKind: LocaleLeafRuntimeKind;
+    action: LocaleLeafDecisionAction;
+    reasons: LocaleMetadataRepairReason[];
+    beforeValue: unknown;
+    afterValue: unknown;
+};
+type LocaleMetadataReport = {
+    mode: LocaleLeafMode;
+    totalSourceLeafPaths: number;
+    unchangedLeaves: number;
+    structuredLeavesWritten: number;
+    promotedLegacyLeaves: number;
+    repairedCorruptLeaves: number;
+    strippedStructuredLeaves: number;
+    missingPathsHydratedFromSource: number;
+    byReason: Record<LocaleMetadataRepairReason, number>;
+    changedPathsSample: LocaleMetadataPathChange[];
+    leafDecisions: LocaleMetadataLeafDecision[];
+};
+
+export type { LocaleMetadataReport as L, StructuredLocaleLeaf as S, LocaleLeafMode as a, LocaleLeafDecisionAction as b, LocaleLeafRuntimeKind as c, LocaleMetadataLeafDecision as d, LocaleMetadataPathChange as e, LocaleMetadataRepairReason as f };