@i18nprune/core 0.1.0

package/dist/coreContext-DMaWLvmB.d.ts

@@ -0,0 +1,388 @@
+import { F as LocaleSegmentSource, b as LocalesFilesystemConfig, G as ScanExcludeConfig, I as I18nPruneConfig } from './root-2-kCaBvQ.js';
+import { a as RuntimeSystemPort } from './capabilities-x74cD2Hu.js';
+import { R as RuntimePathPort } from './path-Bfn3SAts.js';
+import { R as RuntimeFsPort } from './fs-BUYD8ZhA.js';
+import { R as RuntimeAdapters } from './adapters-gp1lXp0T.js';
+
+/**
+ * Canonical **translation surface** for locale JSON: one row per logical key path
+ * (legacy string terminals or structured `{ value, … }` objects — same path layout as the source locale).
+ */
+type TranslationSurfaceShape = 'legacy_string' | 'structured';
+type TranslationSurfaceLeaf = {
+    path: string;
+    value: string;
+    shape: TranslationSurfaceShape;
+    status?: string;
+    confidence: number | null;
+    needsReview: boolean | null;
+    needsTranslationAgain?: boolean | null;
+    /** Structured-locale JSON `source` field (`manual`, provider id, …) — same name as on-disk JSON. */
+    source?: string;
+    /** In-memory segment file provenance for multi-file layouts; never persisted as this object. */
+    fileOrigin?: LocaleSegmentSource;
+    structuredMetaComplete?: boolean;
+};
+
+/**
+ * Structured scan-walk debug events (directory / file skips while listing sources).
+ *
+ * Core does not print these — it only invokes an optional listener so hosts stay
+ * runtime-agnostic (no `console` in core). Register via {@link RunOptions.onScanDebug}
+ * or pass `onScanDebug` to {@link listSourceFiles}.
+ */
+type ScanDebugSkipDirectoryEvent = {
+    kind: 'skip_directory';
+    /** Path relative to scan root (POSIX separators). */
+    relativePath: string;
+    /** Directory entry basename. */
+    basename: string;
+    /** Human-readable reason (built-in skip, `exclude.dirs`, regex, …). */
+    reason: string;
+};
+type ScanDebugSkipFileEvent = {
+    kind: 'skip_file';
+    relativePath: string;
+    basename: string;
+    reason: string;
+};
+type ScanDebugEvent = ScanDebugSkipDirectoryEvent | ScanDebugSkipFileEvent;
+/** Optional per-call listener for {@link listSourceFiles} (overrides global when both set: per-call wins). */
+type ListSourceFilesOptions = {
+    onScanDebug?: (event: ScanDebugEvent) => void;
+};
+
+/** Shared hard cap for translation worker concurrency across core and hosts. */
+declare const TRANSLATE_WORKERS_CAP = 64;
+/**
+ * Environment variable **names** consumed by the translator. Hosts pass an `env` map; core never
+ * touches `process.*`. Keep these co-located with the constants the resolvers read.
+ */
+declare const ENV_TRANSLATE_MAX_WORKERS: "I18NPRUNE_TRANSLATE_MAX_WORKERS";
+declare const ENV_TRANSLATE_PROVIDER: "I18NPRUNE_TRANSLATE_PROVIDER";
+declare const ENV_TRANSLATE_DEEPL_API_KEY: "I18NPRUNE_TRANSLATE_DEEPL_API_KEY";
+declare const ENV_TRANSLATE_LIBRE_URL: "I18NPRUNE_TRANSLATE_LIBRE_URL";
+declare const ENV_TRANSLATE_LLM_API_KEY: "I18NPRUNE_TRANSLATE_LLM_API_KEY";
+declare const ENV_TRANSLATE_LLM_BASE_URL: "I18NPRUNE_TRANSLATE_LLM_BASE_URL";
+declare const ENV_TRANSLATE_LLM_MODEL: "I18NPRUNE_TRANSLATE_LLM_MODEL";
+type TranslatorEnv = Readonly<Record<string, string | undefined>>;
+
+/** Global CLI run flags surfaced on `Context.run`. */
+type RunOptions = {
+    json: boolean;
+    /** Pretty-print JSON envelopes when `--json` is enabled. */
+    jsonPretty: boolean;
+    /** Less non-essential output. */
+    quiet: boolean;
+    /** Suppress informational and warning lines; still emit errors. */
+    silent: boolean;
+    /**
+     * When true, the CLI registers {@link RunOptions.onScanDebug} to print scan skip events to stderr.
+     * Hosts may set this for their own UX without wiring a sink.
+     */
+    debugScan: boolean;
+    /** When true, the CLI may print report-cache dispatch/invalidation diagnostics. */
+    debugCache: boolean;
+    /**
+     * When set and {@link RunOptions.silent} is false, the scanner invokes this for each skip
+     * (directory walk skip, file excluded, non-source extension). Core never uses `console`;
+     * the Node CLI assigns a listener that formats lines to stderr when `--debug-scan` is on
+     * (the sink may still choose to suppress output when {@link RunOptions.quiet} is true).
+     */
+    onScanDebug?: (event: ScanDebugEvent) => void;
+};
+
+/** File-level diff between a baseline and the current scan, used for `--debug-cache` output. */
+type CacheFileDelta = {
+    added: string[];
+    changed: string[];
+    deleted: string[];
+    unchanged: string[];
+};
+
+/** Whether the on-disk `files.json` index is usable as a diff baseline. */
+type FilesIndexStatus = {
+    kind: 'ok';
+} | {
+    kind: 'missing';
+} | {
+    kind: 'malformed';
+} | {
+    kind: 'empty';
+};
+declare function filesIndexIsUsable(status: FilesIndexStatus): boolean;
+
+type CacheRebuildMode = 'partial' | 'full';
+type AnalysisRebuildStrategy = 'full' | 'partial' | 'reuse';
+type CacheRebuildConfig = {
+    rebuild: CacheRebuildMode;
+    fullRescanThresholdPercent: number;
+};
+type ClassifiedSrcDelta = {
+    added: string[];
+    changed: string[];
+    deleted: string[];
+};
+type ClassifiedCacheFileDelta = {
+    src: ClassifiedSrcDelta;
+    sourceLocale: string[];
+    targetLocale: string[];
+    layoutChanged: boolean;
+    filesIndexStatus: FilesIndexStatus;
+};
+type AnalysisRebuildReason = 'config_rebuild_full' | 'layout_changed' | 'source_locale_changed' | 'source_locale_partial' | 'target_locale_only' | 'locale_or_non_src_changed' | 'no_previous_cache' | 'src_threshold' | 'src_partial' | 'files_index_missing' | 'files_index_malformed' | 'files_index_empty' | 'files_index_stale' | 'files_index_recovered';
+type AnalysisRebuildDecision = {
+    strategy: AnalysisRebuildStrategy;
+    reason: AnalysisRebuildReason;
+    thresholdPercent?: number;
+    srcAffected?: number;
+    trackedSrcCount?: number;
+    /** Present on miss when src bucket was classified (debug-cache detail). */
+    srcDelta?: ClassifiedSrcDelta;
+};
+/** Context passed to `CachedProjectInput.producer` on cache miss. */
+type CacheProducerContext<T> = {
+    delta: CacheFileDelta;
+    classified: ClassifiedCacheFileDelta;
+    previous?: T;
+    trackedSrcCount: number;
+    rebuildConfig: CacheRebuildConfig;
+    analysisRebuild?: AnalysisRebuildDecision;
+};
+
+/** Resolved filesystem layout for locale bundle I/O (after defaults). */
+type LocalesLayoutMode = NonNullable<LocalesFilesystemConfig['mode']>;
+type LocalesLayoutStructure = NonNullable<LocalesFilesystemConfig['structure']>;
+/**
+ * Normalized layout descriptor passed to {@link readLocaleBundle} / {@link writeLocaleBundle}.
+ *
+ * @remarks `directoryAbsolute` is the configured bundle root (`paths.localesDir` on core context).
+ */
+type ResolvedLocalesLayout = {
+    mode: LocalesLayoutMode;
+    structure: LocalesLayoutStructure;
+    directoryAbsolute: string;
+    config: LocalesFilesystemConfig;
+};
+
+/** Layout fingerprint stored in `files.json` (`mode` + `structure` + config paths). */
+type CachedLocalesLayout = {
+    mode: LocalesLayoutMode;
+    structure: LocalesLayoutStructure;
+    directory: string;
+    source: string;
+};
+
+/** Per-file hash/size/mtime record stored in `files.json`. */
+type CacheProjectFileRecord = {
+    hash: string;
+    size: number;
+    mtimeMs: number;
+    updatedAt: string;
+};
+
+/** Why the cache was disabled for this run (or `'default'` when enabled normally). */
+type CacheDisableReason = 'default' | 'cli_no_cache' | 'config_disabled' | 'project_root_missing' | 'cache_dir_unavailable' | 'cache_io_error' | 'cache_oversize' | 'cache_malformed' | 'cache_read_only';
+/** Resolved cache paths and flags for the current run, produced by `initializeCacheState`. */
+type CacheState = {
+    enabled: boolean;
+    reason: CacheDisableReason;
+    rootDir: string;
+    metaPath: string;
+    projectId: string;
+    projectRoot: string;
+    projectDir: string;
+    filesPath: string;
+    /** Project scan payload (`analysis.json`). */
+    analysisPath: string;
+    /** Per-target translation cache directory (`translations/`). */
+    translationsDir: string;
+    /** When true, cache reads are allowed but project cache files are not written. */
+    readOnly: boolean;
+};
+/** Non-fatal diagnostic emitted when a cache file is corrupt, oversized, or inaccessible. */
+type CacheWarning = {
+    code: CacheDisableReason;
+    message: string;
+    path?: string;
+};
+type CacheProjectsIndex = {
+    version: number;
+    updatedAt: string;
+    projects: Record<string, string>;
+    maintenance: {
+        runCount: number;
+        healEveryRuns: number;
+        lastHealAt?: string;
+    };
+};
+type CacheProjectFilesState = {
+    version: number;
+    updatedAt: string;
+    files: Record<string, CacheProjectFileRecord>;
+    /** Bundle-relative locale segment paths allowed by `localesLayout`. */
+    localeSegments?: Record<string, CacheProjectFileRecord>;
+    localesLayout?: CachedLocalesLayout;
+};
+type CacheProjectRunState = {
+    version: number;
+    updatedAt: string;
+    projectId: string;
+    data: unknown;
+    /**
+     * Digest of the tracked `files.json` map when `data` was produced. Compared on cache hit so an
+     * older `analysis.json` cannot serve after `files.json` was refreshed.
+     */
+    inputFilesEpoch?: string;
+};
+type CacheDispatchStatus = 'hit' | 'miss' | 'bypass' | 'disabled';
+type CacheDispatchReason = 'cache_hit' | 'no_cache' | 'cache_unavailable' | 'run_missing' | 'files_changed' | 'files_index_recovered' | 'run_binding_stale' | 'producer_succeeded' | 'run_invalid';
+type CacheHashText = (text: string) => string;
+/** Host-injected IO adapters and utilities used by all cache operations. */
+type CacheRuntime = {
+    fs: RuntimeFsPort;
+    path: RuntimePathPort;
+    system: RuntimeSystemPort;
+    hashText?: CacheHashText;
+    byteLength?: (text: string) => number;
+    fileSize?: (filePath: string) => number | undefined;
+    writeTextAtomic?: (filePath: string, content: string) => void;
+    deleteDir?: (dirPath: string) => void;
+};
+type CacheStateInput = {
+    projectRoot: string;
+    cacheRootDir: string;
+    noCache?: boolean;
+    disabledReason?: CacheDisableReason;
+    runtime: CacheRuntime;
+    /** When true, treat cache as read-through: no writes to project cache files. */
+    cacheReadOnly?: boolean;
+};
+type CacheDispatchPaths = {
+    meta: string;
+    files: string;
+    analysis: string;
+    projectDir: string;
+};
+/** When a miss is due to `run_binding_stale`, surfaces what `--debug-cache` should compare. */
+type CacheInputFilesEpochDebug = {
+    cached?: string;
+    current: string;
+};
+/** Result metadata from a single cache dispatch (hit/miss, reason, delta, warnings). */
+type CacheDispatchInfo = {
+    status: CacheDispatchStatus;
+    reason: CacheDispatchReason;
+    warnings: CacheWarning[];
+    delta?: CacheFileDelta;
+    paths?: CacheDispatchPaths;
+    inputFilesEpochDebug?: CacheInputFilesEpochDebug;
+    /** Set when analysis was rebuilt on miss (`--debug-cache` surfaces strategy). */
+    analysisRebuild?: AnalysisRebuildDecision;
+    /** Set when `files.json` was missing, malformed, or empty on load. */
+    filesIndexStatus?: FilesIndexStatus;
+};
+type CacheDispatchResult<T> = {
+    data: T;
+    cache: CacheDispatchInfo;
+};
+/** Input bag for `getOrBuildCachedProjectData` — describes what to cache and how to validate it. */
+type CachedProjectInput<T> = {
+    state: CacheState;
+    runtime: CacheRuntime;
+    sourceLocalePath: string;
+    srcRoot: string;
+    localesDir: string;
+    locales: LocalesFilesystemConfig;
+    exclude?: ScanExcludeConfig;
+    producer: (ctx?: CacheProducerContext<T>) => T;
+    parseCachedData?: (data: unknown) => {
+        ok: true;
+        data: T;
+    } | {
+        ok: false;
+    };
+    rebuildConfig?: CacheRebuildConfig;
+    /**
+     * Pre-loaded `files.json` baseline from before any dispatch in this run. When provided, the
+     * delta is computed against these records so writes during the run do not mask real file changes.
+     */
+    baselineFiles?: Record<string, CacheProjectFileRecord>;
+};
+
+/** Severity for {@link LocaleReadDiagnostic} (hosts map to log level / UI). */
+type LocaleReadDiagnosticLevel = 'info' | 'warn' | 'error';
+/**
+ * Structured locale I/O signal from the shared locale reader layer (no `console.*` in core).
+ *
+ * @remarks Hosts (CLI, extension) subscribe via `onDiagnostic` or inspect `diagnostics[]` on results.
+ */
+type LocaleReadDiagnostic = {
+    level: LocaleReadDiagnosticLevel;
+    /** Stable machine id for filtering (not a CLI `--json` issue code unless wired explicitly). */
+    code: string;
+    message: string;
+    path?: string;
+};
+
+/** Cached read result for one on-disk locale segment file (absolute path key). */
+type LocaleSegmentReadSnapshot = {
+    ok: true;
+    absolutePath: string;
+    document: unknown;
+    leaves: TranslationSurfaceLeaf[];
+    text: string;
+} | {
+    ok: false;
+    absolutePath: string;
+    diagnostics: LocaleReadDiagnostic[];
+};
+/** Merged translation-surface leaves for one locale code (all segments when multi-file). */
+type LocaleCodeReadSnapshot = {
+    localeCode: string;
+    document: unknown;
+    leaves: TranslationSurfaceLeaf[];
+};
+/**
+ * In-memory locale read store for one command / {@link CoreContext} lifetime.
+ * Segment entries hold reader output with full {@link TranslationSurfaceLeaf} identity;
+ * locale-code entries hold merged leaves for multi-segment layouts.
+ */
+type LocaleReadCache = {
+    readonly segments: Map<string, LocaleSegmentReadSnapshot>;
+    readonly localeCodes: Map<string, LocaleCodeReadSnapshot>;
+};
+
+/** Resolved project paths (absolute); hosts compute once (CLI: `resolveContext`). */
+type CoreResolvedPaths = {
+    readonly sourceLocale: string;
+    readonly localesDir: string;
+    readonly srcRoot: string;
+};
+/**
+ * L2 bundle for project ops (`runValidate`, `runSync`, `runGenerate`, …). Same adapters/env rules as
+ * {@link TranslateContext}: required, no runtime defaults inside core.
+ */
+type CoreContext = {
+    readonly config: I18nPruneConfig;
+    readonly adapters: RuntimeAdapters;
+    readonly env: TranslatorEnv;
+    readonly paths: CoreResolvedPaths;
+    /**
+     * When **`false`**, no **`i18nprune.config.*`** was found on disk (CLI: **`configExists()`**).
+     * Hosts omit this field when unknown; **`runProjectReadiness`** only enforces **`configFilePresent`**
+     * when **`configFileLoaded === false`**.
+     */
+    readonly configFileLoaded?: boolean;
+    readonly run?: RunOptions;
+    readonly cache?: {
+        readonly state: CacheState;
+        readonly runtime: CacheRuntime;
+        /** Pre-loaded `files.json` baseline; shared across sibling dispatches for accurate delta. */
+        readonly baselineFiles?: Record<string, CacheProjectFileRecord>;
+    };
+    /** Per-run in-memory locale JSON reads (segment + merged locale-code views). */
+    readonly localeRead: LocaleReadCache;
+};
+
+export { ENV_TRANSLATE_PROVIDER as $, type AnalysisRebuildDecision as A, type CachedProjectInput as B, type CoreContext as C, type ClassifiedCacheFileDelta as D, type ClassifiedSrcDelta as E, type FilesIndexStatus as F, type LocaleCodeReadSnapshot as G, type LocaleReadCache as H, type LocaleReadDiagnosticLevel as I, type LocaleSegmentReadSnapshot as J, type LocalesLayoutMode as K, type LocaleReadDiagnostic as L, type LocalesLayoutStructure as M, type RunOptions as N, type ScanDebugSkipDirectoryEvent as O, type ScanDebugSkipFileEvent as P, type TranslationSurfaceShape as Q, type ResolvedLocalesLayout as R, type ScanDebugEvent as S, type TranslationSurfaceLeaf as T, filesIndexIsUsable as U, ENV_TRANSLATE_DEEPL_API_KEY as V, ENV_TRANSLATE_LIBRE_URL as W, ENV_TRANSLATE_LLM_API_KEY as X, ENV_TRANSLATE_LLM_BASE_URL as Y, ENV_TRANSLATE_LLM_MODEL as Z, ENV_TRANSLATE_MAX_WORKERS as _, type TranslatorEnv as a, TRANSLATE_WORKERS_CAP as a0, type CacheWarning as b, type CoreResolvedPaths as c, type CacheRebuildMode as d, type CacheProjectFileRecord as e, type CachedLocalesLayout as f, type CacheRebuildConfig as g, type ListSourceFilesOptions as h, type CacheDispatchInfo as i, type CacheDispatchStatus as j, type AnalysisRebuildReason as k, type AnalysisRebuildStrategy as l, type CacheDisableReason as m, type CacheDispatchPaths as n, type CacheDispatchReason as o, type CacheDispatchResult as p, type CacheFileDelta as q, type CacheHashText as r, type CacheInputFilesEpochDebug as s, type CacheProducerContext as t, type CacheProjectFilesState as u, type CacheProjectRunState as v, type CacheProjectsIndex as w, type CacheRuntime as x, type CacheState as y, type CacheStateInput as z };

package/dist/fs-BUYD8ZhA.d.ts

@@ -0,0 +1,20 @@
+type RuntimeDirEntry = {
+    name: string;
+    kind: 'file' | 'directory' | 'other';
+};
+type RuntimeFsPathKind = RuntimeDirEntry['kind'] | 'missing';
+type RuntimeReadFsPort = {
+    exists: (filePath: string) => boolean | Promise<boolean>;
+    readText: (filePath: string) => string | Promise<string>;
+};
+type RuntimeFsPort = RuntimeReadFsPort & {
+    statKind: (filePath: string) => RuntimeFsPathKind | Promise<RuntimeFsPathKind>;
+    listDir: (dirPath: string) => RuntimeDirEntry[] | Promise<RuntimeDirEntry[]>;
+    writeText: (filePath: string, content: string) => void | Promise<void>;
+    deleteFile: (filePath: string) => void | Promise<void>;
+    mkdirp: (dirPath: string) => void | Promise<void>;
+    /** When set, returns the canonical path for cycle-safe directory walks (Node: `fs.realpathSync`). */
+    realpath?: (filePath: string) => string;
+};
+
+export type { RuntimeFsPort as R, RuntimeDirEntry as a, RuntimeReadFsPort as b, RuntimeFsPathKind as c };