@x18n/ui 0.0.0-stage → 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+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/dist/index.d.mts

@@ -0,0 +1,255 @@
+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;
+}
+/** 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 ---- */
+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;
+  /** 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[];
+}
+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;
+}
+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)[];
+}
+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, KeyDetail, KeyQuery, KeyRow, KeyTable, LocaleSummary, MessageView, OpenQuery, PlanQuery, PlanView, ProjectList, ProjectQuery, ProjectSummary, PromptQuery, Snippet, UiEditOp, UiLocation, UiProject, UsageQuery, UsageView, RpcOptions as X18nDevframeOptions, X18nState };