@i18nprune/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 i18nprune contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+<div align="center">
+
+  <h1>@i18nprune/core</h1>
+
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/zamdevio/i18nprune/blob/main/LICENSE)
+  [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+  [![npm](https://img.shields.io/npm/v/@i18nprune/core?label=npm)](https://www.npmjs.com/package/@i18nprune/core)
+
+  <p><strong>Validate · sync · generate · review · quality · cleanup · doctor · report · share</strong></p>
+  <p>
+    Runtime-neutral domain engine for <a href="https://i18nprune.dev">i18nprune</a> — same behavior as the CLI, without shelling out.
+  </p>
+  <p>
+    <a href="https://docs.i18nprune.dev">Documentation</a> ·
+    <a href="#quick-start">Quick start</a> ·
+    <a href="#subpath-exports">Subpaths</a> ·
+    <a href="https://www.npmjs.com/package/i18nprune">CLI package</a>
+  </p>
+</div>
+
+---
+
+Pure TypeScript engine for locale validation, sync, translation, diagnostics, and hosted share/report workflows. **No `console.*` and no direct `process.*` in core** — your host passes **runtime adapters** and an **env** object so the same logic runs in Node scripts, CI, browsers, and edge workers.
+
+## Install
+
+Requires **Node.js >= 18**.
+
+```bash
+npm install @i18nprune/core
+# or: pnpm add @i18nprune/core
+# or: yarn add @i18nprune/core
+```
+
+## Quick start
+
+```ts
+import { resolveContext, runSync } from '@i18nprune/core';
+import { createNodeRuntimeAdapters } from '@i18nprune/core/runtime/node';
+
+const ctx = await resolveContext({
+  projectRoot: process.cwd(),
+  adapters: createNodeRuntimeAdapters(),
+});
+
+const result = await runSync(
+  ctx,
+  { dryRun: true },
+  { onProgress: () => {} },
+);
+
+console.log(result.summary);
+```
+
+Use **`defineConfig`** / **`loadConfig`** from `@i18nprune/core/config` when you want the same `i18nprune.config.ts` contract as the CLI.
+
+## Why embed the SDK
+
+| Benefit | What you get |
+|--------|----------------|
+| **Same engine as CLI** | `runValidate`, `runSync`, `runGenerate`, … share issue codes and cache rules with `i18nprune --json`. |
+| **Host-owned UX** | Progress, logging, and exit policy stay in your app; core returns structured results. |
+| **Runtime choice** | Node, browser (`runtime/web`), or edge (`runtime/edge`) adapter factories — one implementation graph per surface. |
+| **Granular imports** | Subpath exports keep bundles small (`/validate`, `/sync`, `/generate`, …). |
+| **Advanced integrations** | Cache, share upload prep, report ingest validation, and translation providers without subprocess overhead. |
+
+Cross-platform behavior matches the CLI: Linux, macOS, and Windows path and cache semantics are parity-tested in the monorepo.
+
+## Subpath exports
+
+Published **`exports`** (see `package.json`):
+
+| Subpath | Typical use |
+|---------|----------------|
+| `@i18nprune/core` | Root barrel: `runXxx`, `resolveContext`, namespaces (`validate`, `sync`, `translator`, …). |
+| `@i18nprune/core/config` | `defineConfig`, schema, path resolution. |
+| `@i18nprune/core/validate` | Validation-only graph. |
+| `@i18nprune/core/sync` | Locale shape sync / prune. |
+| `@i18nprune/core/generate` | Provider translation runs. |
+| `@i18nprune/core/missing` | Missing-key workflows. |
+| `@i18nprune/core/quality` | Quality checks. |
+| `@i18nprune/core/cleanup` | Cleanup operations. |
+| `@i18nprune/core/init` | Project bootstrap helpers. |
+| `@i18nprune/core/locales` | Locale layout and listing helpers. |
+| `@i18nprune/core/shared` | Shared primitives (JSON, scanner, constants, run helpers) — namespaced + flat re-exports. |
+| `@i18nprune/core/types` | Public type barrels. |
+| `@i18nprune/core/report-schema` | `ProjectReportDocument` Zod schema and ingest validation. |
+| `@i18nprune/core/runtime/node` | Node `fs` / path adapters. |
+| `@i18nprune/core/runtime/web` | Browser-safe adapter surface. |
+| `@i18nprune/core/runtime/edge` | Worker / edge adapter surface. |
+| `@i18nprune/core/runtime/helpers/sync` | Sync FS helpers shared across runtimes. |
+
+Prefer the **smallest subpath** that fits your bundle; fall back to the root entry when you need several domains in one script.
+
+## Operation entry points
+
+Command-equivalent **`runXxx`** functions (non-exhaustive):
+
+| Operation | Entry | CLI twin |
+|-----------|--------|----------|
+| Validate | `runValidate` | `i18nprune validate` |
+| Sync | `runSync` | `i18nprune sync` |
+| Generate | `runGenerate` | `i18nprune generate` |
+| Translate | `runTranslate` | provider pipeline |
+| Missing | `runMissing` | `i18nprune missing` |
+| Quality | `runQuality` | `i18nprune quality` |
+| Review | `runReview` | `i18nprune review` |
+| Cleanup | `runCleanup` | `i18nprune cleanup` |
+| Doctor | `runDoctor` | `i18nprune doctor` |
+| Report | `runReport` | `i18nprune report` |
+| Share | `runShare` | `i18nprune share` |
+| Init | `runInit` | `i18nprune init` |
+
+Deep wiring table (maintainer clone): `maintainer/systems/operations/entrypoints.md`.
+
+## Runtime adapters
+
+| Host | Import |
+|------|--------|
+| Node / scripts / CI | `@i18nprune/core/runtime/node` |
+| Browser tooling | `@i18nprune/core/runtime/web` |
+| Workers / edge | `@i18nprune/core/runtime/edge` |
+
+Docs: [Runtime overview](https://docs.i18nprune.dev/runtime/).
+
+## Config, cache, and contracts
+
+- **Config:** `locales.structure`, cache profiles (`safe` | `balanced` | `fast`), translation providers — see [Config hub](https://docs.i18nprune.dev/config/).
+- **Cache:** per-project analysis + persisted translation cache; hosts must not fork rebuild policy — see [CLI cache](https://docs.i18nprune.dev/cli/cache.md).
+- **CLI JSON parity:** stable issue codes and `--json` envelope helpers via `result` exports — see [CLI JSON](https://docs.i18nprune.dev/cli/json.md) and [Issues](https://docs.i18nprune.dev/issues/).
+- **Reports:** build payloads with `runReport`; validate ingest with `@i18nprune/core/report-schema` before upload.
+
+## Examples (monorepo)
+
+Runnable SDK samples live under `examples/sdk/` in the [i18nprune repository](https://github.com/zamdevio/i18nprune):
+
+- `examples/sdk/sync/runSync.ts`
+- `examples/sdk/generate/runGenerate.ts`
+- `examples/sdk/missing/runMissing.ts`
+- `examples/sdk/quality/runQuality.ts`
+- `examples/sdk/review/runReview.ts`
+- `examples/sdk/doctor/runDoctor.ts`
+- `examples/sdk/share/runShareList.ts`
+- `examples/sdk/translate/runTranslate.ts`
+
+## CLI-only users
+
+If you only need the terminal tool, install the root package instead:
+
+```bash
+npm install -g i18nprune
+```
+
+Bundled programmatic surface: `import … from 'i18nprune/core'` (rolled build, not granular subpaths).
+
+## Documentation
+
+- [SDK operations](https://docs.i18nprune.dev/sdk/operations.html)
+- [Architecture](https://docs.i18nprune.dev/architecture/)
+- [Commands](https://docs.i18nprune.dev/commands/)
+- Live site: [docs.i18nprune.dev](https://docs.i18nprune.dev)
+
+## License
+
+MIT — see [LICENSE](https://github.com/zamdevio/i18nprune/blob/main/LICENSE) in the monorepo root.

package/dist/adapters-gp1lXp0T.d.ts

@@ -0,0 +1,12 @@
+import { C as CoreEngineRuntime, R as RuntimeNetworkCap } from './capabilities-x74cD2Hu.js';
+
+type RuntimeKind = 'node' | 'web' | 'edge';
+
+/**
+ * Full host binding for CLI / Workers: project I/O, HTTP, and runtime kind.
+ */
+type RuntimeAdapters = CoreEngineRuntime & RuntimeNetworkCap & {
+    kind: RuntimeKind;
+};
+
+export type { RuntimeAdapters as R, RuntimeKind as a };

package/dist/capabilities-x74cD2Hu.d.ts

@@ -0,0 +1,48 @@
+import { R as RuntimeFsPort } from './fs-BUYD8ZhA.js';
+import { R as RuntimePathPort } from './path-Bfn3SAts.js';
+
+/**
+ * HTTP surface for translation backends and future remote tooling.
+ * Hosts supply `globalThis.fetch` (Node 18+, Workers, browsers) or a test double.
+ */
+type RuntimeNetworkPort = {
+    fetch: typeof globalThis.fetch;
+};
+
+type RuntimeSystemPort = {
+    cwd: () => string;
+    now: () => number;
+};
+
+/** Filesystem port only. */
+type RuntimeFsCap = {
+    fs: RuntimeFsPort;
+};
+/** Path port only. */
+type RuntimePathCap = {
+    path: RuntimePathPort;
+};
+/** Clock / cwd (no filesystem). */
+type RuntimeSystemCap = {
+    system: RuntimeSystemPort;
+};
+/** HTTP client (`fetch`) — not part of {@link CoreEngineRuntime}; use for translate / remote APIs. */
+type RuntimeNetworkCap = {
+    network: RuntimeNetworkPort;
+};
+/**
+ * Filesystem + path: scanning, locale file listing, meta resolution.
+ * Does not include `system` or `network`.
+ */
+type ProjectFilesystemRuntime = RuntimeFsCap & RuntimePathCap;
+/**
+ * Path + system only (no `fs`): resolve relative config paths against `cwd()` without reading files through the port.
+ */
+type ConfigPathSystemRuntime = RuntimePathCap & RuntimeSystemCap;
+/**
+ * Default “project I/O” bundle: `fs`, `path`, and `system` (`cwd` / `now`).
+ * Prefer {@link ProjectFilesystemRuntime} on APIs that never touch `system`.
+ */
+type CoreEngineRuntime = RuntimeFsCap & RuntimePathCap & RuntimeSystemCap;
+
+export type { CoreEngineRuntime as C, ProjectFilesystemRuntime as P, RuntimeNetworkCap as R, RuntimeSystemPort as a, ConfigPathSystemRuntime as b, RuntimeFsCap as c, RuntimeNetworkPort as d, RuntimePathCap as e, RuntimeSystemCap as f };

package/dist/cleanup.d.ts

@@ -0,0 +1,64 @@
+import { S as StringLeaf } from './index-BQuLEQ9b.js';
+import { a as PreservePolicy } from './root-2-kCaBvQ.js';
+import { P as ProjectLiteralKeyUsage, C as CleanupWritePlan, a as CleanupHostHooks, b as CleanupRunOptions, c as CleanupRunResult, d as CleanupSourceSegmentRef } from './sourceSurface-mDtwGo1E.js';
+export { e as CleanupJsonOutput, f as CleanupJsonRunSummary, g as CleanupSegmentWrite, h as CleanupStringPresenceEvidence, R as ResolveCleanupKeysWithStringPresenceInput, r as resolveCleanupKeysWithStringPresencePolicy } from './sourceSurface-mDtwGo1E.js';
+import { C as CoreContext, T as TranslationSurfaceLeaf } from './coreContext-DMaWLvmB.js';
+import 'zod';
+import './path-Bfn3SAts.js';
+import './fs-BUYD8ZhA.js';
+import './providers-0uMEfT6q.js';
+import './index-DdjljwMj.js';
+import './index-X50E1FIX.js';
+import './index-BgG01AKL.js';
+import './capabilities-x74cD2Hu.js';
+import './adapters-gp1lXp0T.js';
+
+/** True when `key` is the root path or nested under a root in `usedRoots` (array segment `[` counts as root). */
+declare function pathUnderRoot(key: string, roots: ReadonlySet<string>): boolean;
+type CleanupCandidateInput = {
+    leaves: readonly StringLeaf[];
+    usage: ProjectLiteralKeyUsage;
+    preserve?: PreservePolicy;
+    uncertainPrefixes: readonly string[];
+    /** When true, drop candidates under {@link pathUnderAnyUncertainPrefix}. */
+    filterUncertainPrefixes: boolean;
+};
+/**
+ * Unused key paths in source locale JSON after scan + preserve + optional uncertain-prefix rules.
+ */
+declare function computeCleanupCandidateKeys(input: CleanupCandidateInput): {
+    allKeyPaths: Set<string>;
+    candidates: string[];
+    excludedUncertain: number;
+};
+
+/**
+ * Pure cleanup application: remove candidate key paths from one locale JSON object.
+ */
+declare function applyCleanupKeysToLocaleJson(localeJson: unknown, keysToRemove: readonly string[]): {
+    next: unknown;
+    removedPaths: string[];
+};
+
+declare function createCleanupSourceWritePlan(ctx: CoreContext, keysToRemove: readonly string[]): CleanupWritePlan;
+declare function writeCleanupPlan(ctx: CoreContext, plan: CleanupWritePlan): void;
+declare function emitCleanupAbortMessage(host: Pick<CleanupHostHooks, 'emit' | 'runId'>, reason: 'no_keys_approved' | 'declined_confirmation'): void;
+declare function emitCleanupAskIgnoredMessage(host: Pick<CleanupHostHooks, 'emit' | 'runId'>): void;
+declare function emitCleanupWriteIntro(host: Pick<CleanupHostHooks, 'emit' | 'runId'>, input: {
+    removeCount: number;
+    segmentFileCount: number;
+}): void;
+declare function emitCleanupWriteDone(host: Pick<CleanupHostHooks, 'emit' | 'runId'>, input: {
+    plan: CleanupWritePlan;
+    wrote: boolean;
+}): void;
+declare function runCleanup(ctx: CoreContext, opts: CleanupRunOptions, host: CleanupHostHooks): CleanupRunResult;
+
+/** All string leaves for the configured source locale (one file or merged multi-segment layout). */
+declare function readCleanupSourceLeaves(ctx: CoreContext): TranslationSurfaceLeaf[];
+/** Source-locale segment files (flat_file → one path). */
+declare function listCleanupSourceSegmentPaths(ctx: CoreContext): CleanupSourceSegmentRef[];
+/** Segment files that contain at least one of the given key paths on disk. */
+declare function listCleanupSourceSegmentsForKeys(ctx: CoreContext, keys: readonly string[]): CleanupSourceSegmentRef[];
+
+export { type CleanupCandidateInput, CleanupHostHooks, CleanupRunOptions, CleanupRunResult, CleanupSourceSegmentRef, CleanupWritePlan, applyCleanupKeysToLocaleJson, computeCleanupCandidateKeys, createCleanupSourceWritePlan, emitCleanupAbortMessage, emitCleanupAskIgnoredMessage, emitCleanupWriteDone, emitCleanupWriteIntro, listCleanupSourceSegmentPaths, listCleanupSourceSegmentsForKeys, pathUnderRoot, readCleanupSourceLeaves, runCleanup, writeCleanupPlan };