@x18n/ui 0.0.2 → 0.0.5

package/dist/index.d.mts

@@ -0,0 +1,281 @@
+import { DevframeDefinition } from "devframe";
+import { ExtractCandidate } from "@x18n/builtins/extractors";
+import { Decision, EditOp, FileChange, KeyString, LocaleCode, MessageLeaf, PlaceholderProblem, Project, ProjectExplanation, Severity, TextRange, UsageKind, WireDiagnostic } from "@x18n/core";
+//#region src/node/types.d.ts
+/** A loaded project as the UI sees it. */
+interface UiProject {
+  readonly name: string;
+  /** Absolute root. */
+  readonly root: string;
+  readonly project: Project;
+}
+/** A file position in a project, for "open in editor". */
+interface UiLocation {
+  readonly project: UiProject;
+  /** Path relative to the project root. */
+  readonly path: string;
+  /** 1-based. */
+  readonly line: number;
+  /** 1-based. */
+  readonly column: number;
+}
+/** ---- Inputs ---- */
+interface ProjectQuery {
+  /** Project name; may be omitted when the workspace has one project. */
+  readonly project?: string | undefined;
+}
+interface KeyQuery extends ProjectQuery {
+  readonly key: KeyString;
+}
+interface UsageQuery extends ProjectQuery {
+  readonly key?: KeyString | undefined;
+  readonly path?: string | undefined;
+}
+interface PromptQuery extends ProjectQuery {
+  readonly locale: LocaleCode;
+  readonly keys?: string | readonly KeyString[] | undefined;
+  readonly namespace?: string | undefined;
+  readonly limit?: number | undefined;
+  readonly cursor?: string | undefined;
+  /** Also translate stale translations. */
+  readonly stale?: boolean | undefined;
+}
+/** Edit ops the UI and agents send; extraction has its own functions. */
+type UiEditOp = Exclude<EditOp, {
+  readonly type: "extract" | "format";
+}>;
+interface PlanQuery extends ProjectQuery {
+  readonly ops: readonly UiEditOp[];
+}
+interface ApplyQuery extends PlanQuery {
+  /** Decision id to option id; unanswered decisions take their default. */
+  readonly answers?: Readonly<Record<string, string>> | undefined;
+  /** Write values whose placeholders differ from the source value. */
+  readonly force?: boolean | undefined;
+}
+interface ExtractQuery extends ProjectQuery {
+  readonly files?: readonly string[] | undefined;
+}
+type ExtractPlanItem = Pick<ExtractCandidate, "path" | "range" | "original" | "key" | "value" | "replacement" | "imports">;
+interface ExtractApplyQuery extends ProjectQuery {
+  readonly items: readonly ExtractPlanItem[];
+}
+interface OpenQuery extends ProjectQuery {
+  readonly path: string;
+  readonly line: number;
+  readonly column: number;
+}
+interface PageQuery {
+  readonly limit?: number | undefined;
+  readonly cursor?: string | undefined;
+}
+interface AgentKeysQuery extends ProjectQuery, PageQuery {
+  readonly glob?: string | undefined;
+  readonly missing?: LocaleCode | undefined;
+  readonly unused?: boolean | undefined;
+  readonly namespace?: string | undefined;
+  readonly values?: boolean | undefined;
+}
+interface AgentUsagesQuery extends UsageQuery, PageQuery {}
+interface AgentCheckQuery extends ProjectQuery, PageQuery {
+  readonly only?: readonly string[] | undefined;
+  readonly locale?: readonly LocaleCode[] | undefined;
+}
+interface AgentSetQuery extends ProjectQuery {
+  readonly messages: Readonly<Record<LocaleCode, Readonly<Record<string, MessageLeaf>>>>;
+  readonly force?: boolean | undefined;
+}
+interface Confirmable {
+  readonly confirm?: boolean | undefined;
+  readonly answers?: Readonly<Record<string, string>> | undefined;
+}
+interface AgentRenameQuery extends ProjectQuery, Confirmable {
+  readonly from: KeyString;
+  readonly to: KeyString;
+  readonly usages?: boolean | undefined;
+}
+interface AgentDeleteQuery extends ProjectQuery, Confirmable {
+  readonly key: KeyString;
+  readonly locales?: readonly LocaleCode[] | undefined;
+}
+/** ---- Outputs ---- */
+/** When a message last changed, from the history providers (git). */
+interface HistoryView {
+  /** Milliseconds since the epoch; null for a local change the provider does not know yet. */
+  readonly at: number | null;
+  /** Commit sha or another provider revision. */
+  readonly revision: string | undefined;
+  readonly author: string | undefined;
+}
+interface LocaleSummary {
+  readonly code: LocaleCode;
+  readonly displayName: string | undefined;
+  readonly flag: string | undefined;
+  readonly total: number;
+  readonly translated: number;
+  readonly missing: number;
+  readonly empty: number;
+  /** Translations older than their source message. */
+  readonly outdated: number;
+  /** One decimal, rounded down. */
+  readonly percent: number;
+}
+interface DiagnosticCounts {
+  readonly errors: number;
+  readonly warnings: number;
+  /** Infos and hints. */
+  readonly infos: number;
+  readonly byCode: readonly {
+    readonly code: string;
+    readonly severity: Severity;
+    readonly count: number;
+  }[];
+}
+interface ProjectSummary {
+  readonly name: string;
+  readonly sourceLocale: LocaleCode;
+  readonly namespaced: boolean;
+  readonly locales: readonly LocaleSummary[];
+  readonly resources: number;
+  readonly keys: number;
+  readonly usages: number;
+  readonly diagnostics: DiagnosticCounts;
+  /** Presets that are listed in the config or detected. */
+  readonly presets: readonly string[];
+  /** The latest message changes in history, local changes first. */
+  readonly changes: readonly (HistoryView & {
+    readonly key: KeyString;
+    readonly locale: LocaleCode;
+  })[];
+}
+interface ProjectList {
+  readonly projects: readonly ProjectSummary[];
+  readonly openInEditor: boolean;
+}
+interface KeyRow {
+  readonly key: KeyString;
+  readonly namespace: string | undefined;
+  /** Stored value per locale; locales without the key are absent. */
+  readonly values: Readonly<Record<LocaleCode, MessageLeaf>>;
+  /** Locales where the key is missing or empty. */
+  readonly missing: readonly LocaleCode[];
+  readonly unused: boolean;
+  readonly diagnostics: number;
+  /** Locales whose translation is older than the source message. */
+  readonly outdated: readonly LocaleCode[];
+  /** The latest change in any locale (ms); local changes count as now. */
+  readonly changedAt: number | undefined;
+}
+interface KeyTable {
+  readonly project: string;
+  readonly sourceLocale: LocaleCode;
+  readonly locales: readonly LocaleCode[];
+  readonly rows: readonly KeyRow[];
+}
+/** Lines of code around a position. */
+interface Snippet {
+  /** 1-based number of the first line. */
+  readonly line: number;
+  readonly lines: readonly string[];
+}
+interface UsageView {
+  readonly key: KeyString | undefined;
+  readonly raw: string;
+  readonly path: string;
+  /** 1-based. */
+  readonly line: number;
+  /** 1-based. */
+  readonly column: number;
+  readonly kind: UsageKind;
+  readonly dynamic: false | "prefix" | "unknown";
+  /** True for prefix usages that may refer to the key. */
+  readonly possible: boolean;
+  readonly snippet: Snippet;
+}
+interface MessageView {
+  readonly locale: LocaleCode;
+  readonly value: MessageLeaf;
+  readonly path: string;
+  readonly line: number;
+  /** Placeholders in a string value, with offsets in the value. */
+  readonly placeholders: readonly ({
+    readonly text: string;
+  } & TextRange)[];
+  readonly changed: HistoryView | undefined;
+  /** Older than the source message. */
+  readonly outdated: boolean;
+  /** For an outdated translation: the source value when it last changed, when known. */
+  readonly sourceThen: string | undefined;
+}
+interface KeyDetail {
+  readonly project: string;
+  readonly key: KeyString;
+  readonly namespace: string | undefined;
+  readonly messages: readonly MessageView[];
+  readonly missing: readonly LocaleCode[];
+  readonly usages: readonly UsageView[];
+  readonly diagnostics: readonly WireDiagnostic[];
+}
+interface AnalysisView {
+  readonly project: string;
+  readonly diagnostics: readonly WireDiagnostic[];
+  readonly unused: readonly KeyString[];
+  /** Usages whose key is not defined in the source locale. */
+  readonly undefinedUsages: readonly UsageView[];
+}
+type ExplainView = Omit<ProjectExplanation, "root">;
+interface ExplainList {
+  readonly projects: readonly ExplainView[];
+}
+interface ChangeView {
+  readonly type: FileChange["type"];
+  readonly path: string;
+}
+interface PlanView {
+  readonly keys: readonly KeyString[];
+  readonly warnings: readonly string[];
+  readonly decisions: readonly Decision[];
+  readonly changes: readonly ChangeView[];
+  /** Set values whose placeholders differ from the source value. */
+  readonly problems: readonly PlaceholderProblem[];
+}
+interface ApplyView extends PlanView {
+  /** False when placeholder problems blocked the write. */
+  readonly applied: boolean;
+  readonly revision: number;
+}
+/** Shared state `x18n:state`: bumps on every change in any project. Mutable: it is the draft type of `mutate`. */
+interface X18nState {
+  revision: number;
+  changedKeys: KeyString[];
+}
+declare module "devframe" {
+  interface DevframeRpcServerFunctions {
+    "x18n:project": () => ProjectList;
+    "x18n:keys": (query: ProjectQuery) => KeyTable;
+    "x18n:key": (query: KeyQuery) => KeyDetail | null;
+    "x18n:usages": (query: UsageQuery) => UsageView[];
+    "x18n:analysis": (query: ProjectQuery) => AnalysisView;
+    "x18n:explain": () => ExplainList;
+    "x18n:translate-prompt": (query: PromptQuery) => string;
+    "x18n:plan": (query: PlanQuery) => PlanView;
+    "x18n:apply": (query: ApplyQuery) => Promise<ApplyView>;
+    "x18n:extract-candidates": (query: ExtractQuery) => ExtractCandidate[];
+    "x18n:extract-apply": (query: ExtractApplyQuery) => Promise<ApplyView>;
+    "x18n:open-in-editor": (query: OpenQuery) => Promise<void>;
+  }
+  interface DevframeRpcSharedStates {
+    "x18n:state": X18nState;
+  }
+}
+//#endregion
+//#region src/node/rpc.d.ts
+interface RpcOptions {
+  readonly openInEditor?: ((location: UiLocation) => Promise<void>) | undefined;
+}
+//#endregion
+//#region src/node/index.d.ts
+/** The x18n UI, RPC functions and MCP tools over loaded projects, as a devframe definition. */
+export declare function createX18nDevframe(projects: readonly UiProject[], options?: RpcOptions): DevframeDefinition;
+//#endregion
+export type { AgentCheckQuery, AgentDeleteQuery, AgentKeysQuery, AgentRenameQuery, AgentSetQuery, AgentUsagesQuery, AnalysisView, ApplyQuery, ApplyView, ChangeView, DiagnosticCounts, ExplainList, ExplainView, ExtractApplyQuery, ExtractPlanItem, ExtractQuery, HistoryView, KeyDetail, KeyQuery, KeyRow, KeyTable, LocaleSummary, MessageView, OpenQuery, PlanQuery, PlanView, ProjectList, ProjectQuery, ProjectSummary, PromptQuery, Snippet, UiEditOp, UiLocation, UiProject, UsageQuery, UsageView, RpcOptions as X18nDevframeOptions, X18nState };