@x18n/core 0.0.14 → 0.1.0

package/dist/index.d.mts

@@ -139,6 +139,31 @@ declare const errorDefinitions: {
     }) => string;
     fix: string;
   };
+  X18N5001: {
+    why: (p: {
+      path: string;
+      reason: string;
+    }) => string;
+    fix: string;
+  };
+  X18N5003: {
+    why: (p: {
+      reason: string;
+    }) => string;
+    fix: string;
+  };
+  X18N5004: {
+    why: (p: {
+      id: string;
+    }) => string;
+    fix: string;
+  };
+  X18N5005: {
+    why: (p: {
+      id: string;
+    }) => string;
+    fix: string;
+  };
 };
 type ErrorCode = keyof typeof errorDefinitions;
 type X18nError = Diagnostic$1 & {
@@ -159,6 +184,70 @@ interface ErrorInfo {
 export declare function isX18nError(error: unknown): error is X18nError;
 export declare function toErrorInfo(error: unknown): ErrorInfo;
 //#endregion
+//#region src/types/review.d.ts
+type ReviewType = "comment" | "approve" | "request-change" | "suggestion";
+interface ReviewAuthor {
+  readonly name?: string | undefined;
+  readonly email?: string | undefined;
+}
+/** One entry of a review thread, as stored. */
+interface ReviewComment {
+  /** Short random id, unique within the review file. */
+  readonly id: string;
+  readonly type: ReviewType;
+  readonly author?: ReviewAuthor | undefined;
+  /** ISO 8601 time. */
+  readonly time: string;
+  readonly text?: string | undefined;
+  /** The proposed value of a `suggestion`. */
+  readonly suggestion?: string | undefined;
+  /** The value an `approve` approved; the approval is stale once the message has another value. */
+  readonly value?: string | undefined;
+  readonly resolved?: boolean | undefined;
+}
+/** Everything a review store holds. */
+interface ReviewData {
+  /** Comments per key and locale, oldest first. */
+  readonly threads: {
+    readonly [key: KeyString]: {
+      readonly [locale: LocaleCode]: readonly ReviewComment[];
+    };
+  };
+  /** Hash of the source value when x18n last wrote each target message. */
+  readonly sources: {
+    readonly [key: KeyString]: {
+      readonly [locale: LocaleCode]: string;
+    };
+  };
+}
+/** Reads and writes the review file (`review.file`). Core does the I/O and puts writes into edit plans. */
+interface ReviewStore {
+  readonly id: string;
+  /** Throws on invalid content; core reports it as a coded error. */
+  readonly parse: (text: string) => ReviewData;
+  readonly serialize: (data: ReviewData) => string;
+}
+/** Where a thread stands: the last open approval or change request decides, then open suggestions, then open comments. */
+type ReviewState = "changes-requested" | "approved" | "stale-approval" | "suggested" | "commented";
+interface ThreadComment extends ReviewComment {
+  /** An approval of a value the message no longer has. */
+  readonly stale: boolean;
+}
+/** The comments on one message. */
+interface ReviewThread {
+  readonly key: KeyString;
+  readonly locale: LocaleCode;
+  readonly comments: readonly ThreadComment[];
+  /** Undefined when every comment is resolved. */
+  readonly state: ReviewState | undefined;
+}
+interface ReviewFilter {
+  readonly key?: KeyString | undefined;
+  readonly locale?: LocaleCode | undefined;
+  /** Only unresolved comments, and only threads that have some. */
+  readonly open?: boolean | undefined;
+}
+//#endregion
 //#region src/types/model.d.ts
 /** A locale code exactly as written in paths and files: `en`, `zh_CN`, `pt-BR`. Never normalized. */
 type LocaleCode = string;
@@ -277,6 +366,27 @@ type EditOp = {
 } | {
   readonly type: "format";
   readonly paths?: readonly string[];
+} | {
+  readonly type: "review";
+  readonly key: KeyString;
+  readonly locale: LocaleCode;
+  readonly review: ReviewType;
+  readonly text?: string | undefined;
+  /** The proposed value, required for `suggestion`. */
+  readonly suggestion?: string | undefined;
+  readonly author?: ReviewAuthor | undefined;
+  readonly id?: string | undefined;
+  readonly time?: string | undefined;
+} | {
+  readonly type: "resolve-review";
+  readonly id: string;
+} | {
+  readonly type: "apply-suggestion";
+  readonly id: string;
+} | {
+  readonly type: "mark-fresh";
+  readonly key: KeyString;
+  readonly locales?: readonly LocaleCode[] | undefined;
 };
 interface ExtractItem {
   readonly path: string;
@@ -393,6 +503,8 @@ interface Host {
   readonly watch?: ((patterns: readonly string[], onChange: (events: readonly FileEvent[]) => void) => Disposable) | undefined;
   readonly cache?: CacheStore | undefined;
   readonly logger?: Logger | undefined;
+  /** Who writes reviews. The node host reads git `user.name` and `user.email`. */
+  readonly identity?: (() => Promise<ReviewAuthor | undefined>) | undefined;
 }
 //#endregion
 //#region src/types/plugin.d.ts
@@ -646,6 +758,7 @@ interface CheckContext {
   }>;
   /** When a message last changed, from the history providers. Undefined until history is loaded. */
   readonly history: (key: KeyString, locale: LocaleCode) => MessageChange | undefined;
+  readonly reviews: (filter?: ReviewFilter) => readonly ReviewThread[];
 }
 interface Check {
   readonly id: string;
@@ -741,6 +854,8 @@ interface Plugin {
   readonly reporters?: readonly Reporter[] | undefined;
   readonly placeholders?: readonly PlaceholderSyntax[] | undefined;
   readonly histories?: readonly HistoryProvider[] | undefined;
+  /** Only one store is active: the last one, so a plugin's store replaces the built-in one. */
+  readonly reviewStores?: readonly ReviewStore[] | undefined;
   /** Turns raw key text into canonical form. The first plugin that returns a value wins. */
   readonly normalizeKey?: ((raw: string, ctx: KeyContext) => string | undefined) | undefined;
   readonly derivedKeys?: readonly string[] | undefined;
@@ -902,6 +1017,14 @@ interface NamespaceOptions {
   /** How `{namespaces}` folders name a namespace: `dot` makes `pages/home` into `pages.home`, `slash` keeps `pages/home`, `camel` makes `todos-page` into `todosPage`. Default `dot`. */
   readonly fromPath?: "dot" | "slash" | "camel" | undefined;
 }
+interface ReviewOptions {
+  /** Default true. */
+  readonly enabled?: boolean | undefined;
+  /** Review file, relative to the project root. Default `.x18n/reviews.yml`. */
+  readonly file?: string | undefined;
+  /** Author of new reviews, instead of the host identity (git `user.name` and `user.email`). */
+  readonly author?: ReviewAuthor | undefined;
+}
 type NamespaceFromPath = NonNullable<NamespaceOptions["fromPath"]>;
 type PluginSpecifier = string | readonly [string, JsonObject];
 /** The part of the config that YAML and JSON files can hold. Validated by `ConfigSchema`. */
@@ -943,6 +1066,8 @@ interface SerializableConfig {
   readonly glossary?: readonly GlossaryEntry[] | undefined;
   /** History providers for stale translations. `false` turns every provider off. Options of a provider sit under its key, such as `git: { maxDepth, since }` (or `git: false`). */
   readonly history?: boolean | HistoryOptions | undefined;
+  /** Review comments, approvals and suggested values on messages, kept in a file tracked in git. */
+  readonly review?: ReviewOptions | undefined;
   /** Monorepo: directories (globs) that are projects inheriting this config. */
   readonly projects?: readonly string[] | undefined;
 }
@@ -1018,6 +1143,11 @@ interface ResolvedConfig {
   readonly ignoreKeys: readonly string[];
   readonly glossary: readonly GlossaryEntry[];
   readonly history: false | HistorySettings;
+  readonly review: {
+    readonly enabled: boolean;
+    readonly file: string;
+    readonly author: ReviewAuthor | undefined;
+  };
   readonly pluginConfigs: Partial<PluginConfigs>;
   /** Origin of each top-level value, for `explain()`. */
   readonly origins: {
@@ -1033,6 +1163,10 @@ export declare function definePlugin<O, const T extends Plugin>(factory: (option
 export declare function definePreset<const T extends Preset>(preset: T): T;
 export declare function defineConfig(config: UserConfig & { readonly [K in keyof PluginConfigs]?: PluginConfigs[K]; }): UserConfig;
 //#endregion
+//#region src/fuzzy.d.ts
+/** Subsequence match score of `query` in `text`, case-insensitive; higher is better, -1 when it does not match. Substring hits rank above every subsequence. */
+export declare function fuzzyScore(query: string, text: string): number;
+//#endregion
 //#region src/keys.d.ts
 /** Canonical string form of a key: `ns:a.b.c`, or `a.b.c` without namespace. */
 export declare function joinKey(namespace: string | undefined, path: readonly string[]): KeyString;
@@ -1143,6 +1277,7 @@ interface PluginRegistry {
   readonly manifests: readonly ManifestReader[];
   readonly extractors: readonly Extractor[];
   readonly histories: readonly HistoryProvider[];
+  readonly reviewStores: readonly ReviewStore[];
   readonly conflicts: readonly CapabilityConflict[];
   /** The loaded format for a file path: config `formats` first, then the first format that claims the extension. */
   readonly formatFor: (path: string, hint?: string) => Format | undefined;
@@ -1265,6 +1400,18 @@ interface KeyQuery {
   /** Only keys without usages. */
   readonly unused?: boolean | undefined;
 }
+interface SearchOptions {
+  /** Only values containing the query; by default a fuzzy (subsequence) match also counts. Both ignore case. */
+  readonly exact?: boolean | undefined;
+}
+/** A key found by its value: the best-matching locale, source first on ties. */
+interface SearchMatch {
+  readonly key: KeyString;
+  readonly locale: LocaleCode;
+  readonly value: string;
+  /** Higher is better; substring hits rank above fuzzy ones. */
+  readonly score: number;
+}
 interface UsageMatch {
   readonly usage: Usage;
   /** True for prefix usages that may refer to the key. */
@@ -1285,6 +1432,7 @@ interface KeyInfo {
   readonly missing: readonly LocaleCode[];
   readonly usages: readonly UsageMatch[];
   readonly diagnostics: readonly Diagnostic[];
+  readonly reviews: readonly ReviewThread[];
 }
 /** The key, or the resource node, under a position. */
 type KeyTarget = {
@@ -1417,6 +1565,8 @@ interface Project {
   /** Extraction templates: config `extract.templates` first, then those of presets. */
   readonly extractTemplates: readonly ExtractTemplate[];
   readonly keys: (query?: KeyQuery) => KeyString[];
+  /** Keys whose value in some locale matches the query, best first. */
+  readonly search: (query: string, options?: SearchOptions) => SearchMatch[];
   readonly get: (key: KeyString) => KeyInfo | undefined;
   readonly message: (key: KeyString, locale: LocaleCode) => Message | undefined;
   /** The message a usage of `key` shows: the key's own, or one of its derived keys (`item` → `item_other`). */
@@ -1443,6 +1593,12 @@ interface Project {
   readonly history: (key: KeyString, locale: LocaleCode) => MessageChange | undefined;
   /** The value a message had at a time (ms), from the provider that knows the message. */
   readonly valueAt: (key: KeyString, locale: LocaleCode, at: number) => MessageLeaf | undefined;
+  /** Review threads, in key order and then locale order. */
+  readonly reviews: (filter?: ReviewFilter) => readonly ReviewThread[];
+  /** The review file when reviews are on and a review store is registered. */
+  readonly reviewFile: string | undefined;
+  /** Author of new reviews: config `review.author`, else the host identity. */
+  readonly reviewAuthor: () => Promise<ReviewAuthor | undefined>;
   /** Parts of a translate or review prompt for an agent or LLM; render with `renderPrompt`. */
   readonly prompt: (kind: "translate" | "review", locale: LocaleCode, options?: PromptOptions) => PromptData;
   readonly explain: () => ProjectExplanation;
@@ -1484,6 +1640,10 @@ type PlaceholderComparer = (source: string, target: string) => {
 export declare function createPlaceholderComparer(syntaxes: readonly PlaceholderSyntax[], find?: (value: string) => readonly Placeholder[]): PlaceholderComparer;
 export declare function placeholderProblems(project: Project, ops: readonly EditOp[]): PlaceholderProblem[];
 //#endregion
+//#region src/project/explain.d.ts
+/** `project.explain()` as the text `x18n doctor` prints. `root` and `configFile` are shown as given. */
+export declare function renderExplanation(e: ProjectExplanation, configFile?: string | undefined): string;
+//#endregion
 //#region src/project/project.d.ts
 interface CreateProjectOptions {
   readonly host: Host;
@@ -1542,6 +1702,15 @@ interface PluginFile {
   } | undefined;
 }
 export declare const PluginFileSchema: v.GenericSchema<PluginFile>;
+/** The review file (`.x18n/reviews.yml`), as the YAML review store reads it. */
+interface ReviewFile {
+  readonly $schema?: string | undefined;
+  /** File format version. */
+  readonly x18n: 1;
+  readonly threads?: ReviewData["threads"] | undefined;
+  readonly sources?: ReviewData["sources"] | undefined;
+}
+export declare const ReviewFileSchema: v.GenericSchema<ReviewFile>;
 interface SchemaIssue {
   readonly path: string;
   readonly message: string;
@@ -1579,4 +1748,4 @@ export declare function rangeContains(range: TextRange, offset: number): boolean
 /** Fast non-cryptographic string hash (cyrb53), as hex. */
 export declare function hashText(text: string): string;
 //#endregion
-export type { Analysis, Answers, ApplyResult, ArgSource, Builtins, CacheStore, CallSpec, CapabilityConflict, Check, CheckContext, CheckIds, CheckLevel, CheckSetting, ConfigContext, ConfigDraft, ConfigOrigin, CreateProjectOptions, Decision, DecisionOption, DetectContext, Diagnostic, DiagnosticInput, Disposable, EditOp, Envelope, ErrorCode, ErrorInfo, ExtractItem, ExtractOptions, ExtractTemplate, Extractor, FileChange, FileEvent, FileScan, FinderContext, Fix, Format, FormatContext, FormatEntry, GlobOptions, GlossaryEntry, HardString, HistoryConfigs, HistoryContext, HistoryOptions, HistoryProvider, HistorySettings, Host, JsonObject, JsonPrimitive, JsonValue, KeyContext, KeyId, KeyInfo, KeyQuery, KeyString, KeyTarget, LazyFormat, LazyScanner, LibraryOptions, LineIndex, LinePosition, LocaleCode, LocaleCoverage, LocaleFinder, LocaleInfo, Location, Logger, ManifestReader, MemoryHost, Message, MessageChange, MessageHistory, MessageLeaf, MessageOp, MessageTree, NamespaceFromPath, NamespaceOptions, NodeRange, OverlayHost, ParseResult, Placeholder, PlaceholderComparer, PlaceholderProblem, PlaceholderSyntax, Plan, Plugin, PluginConfigs, PluginFile, PluginLoader, PluginOption, PluginRegistry, PluginSpecifier, PluralForm, Preset, PresetDetection, PresetEntry, PresetExplanation, PresetFactory, PresetLoader, PresetOption, Project, ProjectChange, ProjectExplanation, PromptContext, PromptData, PromptDraft, PromptItem, PromptOptions, RegexScannerSpec, ReportInput, ReportSummary, Reporter, ReporterContext, ReporterLoader, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ScanContext, ScanResult, Scanner, ScannerEntry, SchemaIssue, Scope, SerializableConfig, Setup, Severity, SourceFile, TextEdit, TextRange, TreeLeaf, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };
+export type { Analysis, Answers, ApplyResult, ArgSource, Builtins, CacheStore, CallSpec, CapabilityConflict, Check, CheckContext, CheckIds, CheckLevel, CheckSetting, ConfigContext, ConfigDraft, ConfigOrigin, CreateProjectOptions, Decision, DecisionOption, DetectContext, Diagnostic, DiagnosticInput, Disposable, EditOp, Envelope, ErrorCode, ErrorInfo, ExtractItem, ExtractOptions, ExtractTemplate, Extractor, FileChange, FileEvent, FileScan, FinderContext, Fix, Format, FormatContext, FormatEntry, GlobOptions, GlossaryEntry, HardString, HistoryConfigs, HistoryContext, HistoryOptions, HistoryProvider, HistorySettings, Host, JsonObject, JsonPrimitive, JsonValue, KeyContext, KeyId, KeyInfo, KeyQuery, KeyString, KeyTarget, LazyFormat, LazyScanner, LibraryOptions, LineIndex, LinePosition, LocaleCode, LocaleCoverage, LocaleFinder, LocaleInfo, Location, Logger, ManifestReader, MemoryHost, Message, MessageChange, MessageHistory, MessageLeaf, MessageOp, MessageTree, NamespaceFromPath, NamespaceOptions, NodeRange, OverlayHost, ParseResult, Placeholder, PlaceholderComparer, PlaceholderProblem, PlaceholderSyntax, Plan, Plugin, PluginConfigs, PluginFile, PluginLoader, PluginOption, PluginRegistry, PluginSpecifier, PluralForm, Preset, PresetDetection, PresetEntry, PresetExplanation, PresetFactory, PresetLoader, PresetOption, Project, ProjectChange, ProjectExplanation, PromptContext, PromptData, PromptDraft, PromptItem, PromptOptions, RegexScannerSpec, ReportInput, ReportSummary, Reporter, ReporterContext, ReporterLoader, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ReviewAuthor, ReviewComment, ReviewData, ReviewFile, ReviewFilter, ReviewOptions, ReviewState, ReviewStore, ReviewThread, ReviewType, ScanContext, ScanResult, Scanner, ScannerEntry, SchemaIssue, Scope, SearchMatch, SearchOptions, SerializableConfig, Setup, Severity, SourceFile, TextEdit, TextRange, ThreadComment, TreeLeaf, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };

package/dist/index.mjs

@@ -225,6 +225,22 @@ const errorDefinitions = {
 	X18N4008: {
 		why: (p) => `Invalid edit input: ${p.reason}`,
 		fix: "Check the input shape against the docs."
+	},
+	X18N5001: {
+		why: (p) => `Review file ${p.path} could not be read: ${p.reason}`,
+		fix: "Fix the file against `schema/reviews.json`, or restore it from git."
+	},
+	X18N5003: {
+		why: (p) => `Reviews are not available: ${p.reason}`,
+		fix: "Set `review.enabled` to true, and fix the review file if the check reports a problem with it."
+	},
+	X18N5004: {
+		why: (p) => `Review not found: ${p.id}`,
+		fix: "List review ids with `x18n review list` (agents: the `x18n_reviews` tool)."
+	},
+	X18N5005: {
+		why: (p) => `Review ${p.id} is not an open suggestion`,
+		fix: "Apply only open reviews of type `suggestion`."
 	}
 };
 /** Raise with `throw errors.X18N2002({ path, reason })`. Core has no reporters: surfaces print what they catch. */
@@ -251,6 +267,24 @@ function toErrorInfo(error) {
 	};
 }
 //#endregion
+//#region src/fuzzy.ts
+/** Subsequence match score of `query` in `text`, case-insensitive; higher is better, -1 when it does not match. Substring hits rank above every subsequence. */
+function fuzzyScore(query, text) {
+	const q = query.toLowerCase();
+	const s = text.toLowerCase();
+	const exact = s.indexOf(q);
+	if (exact !== -1) return 2e3 - Math.min(exact, 1e3);
+	let score = 0;
+	let at = -1;
+	for (const char of q) {
+		const next = s.indexOf(char, at + 1);
+		if (next === -1) return -1;
+		score += next === at + 1 ? 2 : 1;
+		at = next;
+	}
+	return score;
+}
+//#endregion
 //#region src/keys.ts
 /** Canonical string form of a key: `ns:a.b.c`, or `a.b.c` without namespace. */
 function joinKey(namespace, path) {
@@ -701,6 +735,7 @@ function createRegistry(input, config) {
 		manifests: plugins.flatMap((plugin) => plugin.manifests ?? []),
 		extractors: plugins.flatMap((plugin) => plugin.extractors ?? []),
 		histories: plugins.flatMap((plugin) => plugin.histories ?? []),
+		reviewStores: plugins.flatMap((plugin) => plugin.reviewStores ?? []),
 		conflicts,
 		formatById,
 		formatIdFor,
@@ -816,6 +851,10 @@ const namespaceOptions = v.strictObject({
 		"camel"
 	]))
 });
+const reviewAuthor = v.strictObject({
+	name: v.optional(v.string()),
+	email: v.optional(v.string())
+});
 /** Validates YAML and JSON configs, and the serializable part of TS configs. */
 const ConfigSchema = v.strictObject({
 	$schema: v.optional(v.string()),
@@ -855,6 +894,11 @@ const ConfigSchema = v.strictObject({
 	ignoreKeys: v.optional(strings),
 	glossary: v.optional(v.array(glossaryEntry)),
 	history: v.optional(v.union([v.boolean(), v.record(v.string(), v.union([v.literal(false), v.looseObject({})]))])),
+	review: v.optional(v.strictObject({
+		enabled: v.optional(v.boolean()),
+		file: v.optional(v.string()),
+		author: v.optional(reviewAuthor)
+	})),
 	projects: v.optional(strings)
 });
 const PluginFileSchema = v.strictObject({
@@ -896,6 +940,27 @@ const PluginFileSchema = v.strictObject({
 	}))),
 	extract: v.optional(v.strictObject({ templates: v.optional(extractTemplates) }))
 });
+const reviewComment = v.strictObject({
+	id: v.string(),
+	type: v.picklist([
+		"comment",
+		"approve",
+		"request-change",
+		"suggestion"
+	]),
+	author: v.optional(reviewAuthor),
+	time: v.string(),
+	text: v.optional(v.string()),
+	suggestion: v.optional(v.string()),
+	value: v.optional(v.string()),
+	resolved: v.optional(v.boolean())
+});
+const ReviewFileSchema = v.strictObject({
+	$schema: v.optional(v.string()),
+	x18n: v.literal(1),
+	threads: v.optional(v.record(v.string(), v.record(v.string(), v.array(reviewComment)))),
+	sources: v.optional(v.record(v.string(), v.record(v.string(), v.string())))
+});
 /** Validates data against a schema and returns readable issues instead of throwing. */
 function validate(schema, data) {
 	const result = v.safeParse(schema, data);
@@ -975,6 +1040,28 @@ function placeholderProblems(project, ops) {
 	});
 }
 //#endregion
+//#region src/project/explain.ts
+/** `project.explain()` as the text `x18n doctor` prints. `root` and `configFile` are shown as given. */
+function renderExplanation(e, configFile) {
+	const lines = [
+		`# ${e.name} (${e.root})`,
+		`config: ${configFile ?? "none (detection only)"}`,
+		"presets:"
+	];
+	const applied = e.presets.filter((p) => p.reason === "detected" || p.reason === "listed");
+	lines.push(...applied.map((p) => `  ✓ ${p.name} (${p.reason})`));
+	if (applied.length === 0) lines.push("  none");
+	if (e.presets.length > applied.length) lines.push(`  ${e.presets.length - applied.length} others not applied`);
+	lines.push("finders:");
+	for (const f of e.finders) lines.push(`  ${f.id}: ${f.resources.length} resources`, ...f.resources.slice(0, 20).map((path) => `    ${path}`));
+	lines.push("formats:", ...e.formats.filter((f) => f.resources > 0).map((f) => `  ${f.id} (${f.extensions.join(", ")}): ${f.resources} resources`));
+	lines.push("scanners:", ...e.scanners.map((s) => `  ${s.id} (${s.extensions.join(", ") || "none"}): ${s.files} files`));
+	if (e.conflicts.length) lines.push("conflicts:", ...e.conflicts.map((c) => `  .${c.extension}: ${c.winner} wins over ${c.loser}`));
+	if (e.errors.length) lines.push("errors:", ...e.errors.map((err) => `  ${err.name} ${err.why}`));
+	lines.push("config origins:", ...Object.entries(e.config.origins).map(([key, origin]) => `  ${key}: ${origin}`));
+	return lines.join("\n");
+}
+//#endregion
 //#region src/project/history.ts
 const localChange = { updatedAt: Number.POSITIVE_INFINITY };
 /** A target message is stale when it last changed before its source message. */
@@ -1224,7 +1311,7 @@ function computeCoverage(state, options, sourceKeys) {
 			if (value === void 0 || value === "") {
 				if (inherited(key)) continue;
 				(value === void 0 ? missing : empty).push(key);
-			} else if (locale !== sourceLocale && isOutdated(state.history(key, sourceLocale), state.history(key, locale))) outdated.push(key);
+			} else if (locale !== sourceLocale && isOutdated(state.history(key, sourceLocale), state.history(key, locale)) && !state.fresh(key, locale)) outdated.push(key);
 		}
 		return {
 			locale,
@@ -1375,6 +1462,7 @@ function createAnalyzer(options) {
 			localeInfo: options.localeInfo,
 			text: options.text,
 			history: state.history,
+			reviews: state.reviews,
 			*hardStrings() {
 				for (const [path, file] of state.files) for (const hard of file.result.hardStrings ?? []) yield {
 					...hard,
@@ -1402,6 +1490,161 @@ function createAnalyzer(options) {
 	return { analyze };
 }
 //#endregion
+//#region src/project/reviews.ts
+const noReviews = {
+	threads: {},
+	sources: {}
+};
+/** What a review compares: message values as text. */
+function valueText(value) {
+	return value === null ? "" : String(value);
+}
+/** The hash recorded for a source value in `sources`. */
+function sourceHash(value) {
+	return hashText(JSON.stringify(value));
+}
+function reviewState(comments) {
+	const open = comments.filter((comment) => !comment.resolved);
+	const decisive = open.findLast((comment) => comment.type === "approve" || comment.type === "request-change");
+	if (decisive) return decisive.type === "request-change" ? "changes-requested" : decisive.stale ? "stale-approval" : "approved";
+	if (open.some((comment) => comment.type === "suggestion")) return "suggested";
+	return open.length > 0 ? "commented" : void 0;
+}
+/** A short random id that `taken` does not know. */
+function reviewId(taken) {
+	let id;
+	do
+		id = Math.random().toString(36).slice(2, 8);
+	while (id.length < 6 || taken(id));
+	return id;
+}
+function byCode(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Threads in key order, then in the order of `locales`, then any other locale. */
+function listThreads(data, filter, locales, current) {
+	const rank = (locale) => {
+		const i = locales.indexOf(locale);
+		return i < 0 ? locales.length : i;
+	};
+	const out = [];
+	const keys = filter.key === void 0 ? Object.keys(data.threads).sort(byCode) : [filter.key];
+	for (const key of keys) {
+		const byLocale = data.threads[key] ?? {};
+		const codes = Object.keys(byLocale).filter((locale) => filter.locale === void 0 || locale === filter.locale).sort((a, b) => rank(a) - rank(b) || byCode(a, b));
+		for (const locale of codes) {
+			const value = current(key, locale);
+			const comments = byLocale[locale].filter((comment) => !filter.open || !comment.resolved).map((comment) => ({
+				...comment,
+				stale: comment.type === "approve" && comment.value !== void 0 && value !== void 0 && valueText(value) !== comment.value
+			}));
+			if (comments.length > 0) out.push({
+				key,
+				locale,
+				comments,
+				state: reviewState(comments)
+			});
+		}
+	}
+	return out;
+}
+function findReview(data, id) {
+	for (const [key, byLocale] of Object.entries(data.threads)) for (const [locale, comments] of Object.entries(byLocale)) {
+		const comment = comments.find((c) => c.id === id);
+		if (comment) return {
+			key,
+			locale,
+			comment
+		};
+	}
+}
+function sortSection(section) {
+	return Object.fromEntries(Object.entries(section).filter(([, byLocale]) => Object.keys(byLocale).length > 0).sort(([a], [b]) => byCode(a, b)).map(([key, byLocale]) => [key, Object.fromEntries(Object.entries(byLocale).sort(([a], [b]) => byCode(a, b)))]));
+}
+/** Sorted keys and locales, so edits from two branches merge well. */
+function sortReviews(data) {
+	return {
+		threads: sortSection(data.threads),
+		sources: sortSection(data.sources)
+	};
+}
+function rekey(section, from, to) {
+	const { [from]: entry, ...rest } = section;
+	return entry ? {
+		...rest,
+		[to]: entry
+	} : section;
+}
+function without(section, key, locales) {
+	const { [key]: byLocale, ...rest } = section;
+	if (!byLocale || locales === "all") return rest;
+	return {
+		...rest,
+		[key]: Object.fromEntries(Object.entries(byLocale).filter(([locale]) => !locales.includes(locale)))
+	};
+}
+/** Review data being changed by an edit plan. */
+var ReviewDraft = class {
+	data;
+	changed = false;
+	constructor(data) {
+		this.data = data;
+	}
+	update(next) {
+		this.changed = true;
+		this.data = next;
+	}
+	thread(key, locale, comments) {
+		const { threads } = this.data;
+		this.update({
+			...this.data,
+			threads: {
+				...threads,
+				[key]: {
+					...threads[key],
+					[locale]: comments
+				}
+			}
+		});
+	}
+	add(key, locale, comment) {
+		this.thread(key, locale, [...this.data.threads[key]?.[locale] ?? [], comment]);
+	}
+	resolve(id) {
+		const found = findReview(this.data, id);
+		if (found) this.thread(found.key, found.locale, this.data.threads[found.key][found.locale].map((c) => c.id === id ? {
+			...c,
+			resolved: true
+		} : c));
+	}
+	record(key, locale, hash) {
+		const { sources } = this.data;
+		if (sources[key]?.[locale] !== hash) this.update({
+			...this.data,
+			sources: {
+				...sources,
+				[key]: {
+					...sources[key],
+					[locale]: hash
+				}
+			}
+		});
+	}
+	/** Threads and records follow a renamed key. */
+	move(from, to) {
+		if (this.data.threads[from] || this.data.sources[from]) this.update({
+			threads: rekey(this.data.threads, from, to),
+			sources: rekey(this.data.sources, from, to)
+		});
+	}
+	remove(key, locales) {
+		if (this.data.threads[key] || this.data.sources[key]) this.update({
+			threads: without(this.data.threads, key, locales),
+			sources: without(this.data.sources, key, locales)
+		});
+	}
+};
+//#endregion
 //#region src/project/planner.ts
 const safeSegment = /^[\w-]+$/;
 const safeFlat = /^[\w.-]+$/;
@@ -1471,6 +1714,9 @@ var PlanBuilder = class {
 	touched = /* @__PURE__ */ new Set();
 	stateById;
 	config;
+	/** Source values set by this plan, for the source records of targets set after them. */
+	plannedSource = /* @__PURE__ */ new Map();
+	draft;
 	constructor(options, state, answers) {
 		this.options = options;
 		this.state = state;
@@ -1797,6 +2043,7 @@ var PlanBuilder = class {
 		const renamed = keys.includes(op.from) ? /* @__PURE__ */ new Set() : this.renameNode(op.from, op.to);
 		for (const [from, to] of pairs) {
 			this.moveKey(from, to, renamed);
+			this.reviewDraft()?.move(from, to);
 			if (op.usages !== false) this.rewriteUsages(from, to);
 		}
 		if (op.usages === false) return;
@@ -1808,6 +2055,7 @@ var PlanBuilder = class {
 		if (keys.length === 0) throw errors.X18N4006({ key: op.key });
 		for (const key of keys) {
 			this.touched.add(key);
+			this.reviewDraft()?.remove(key, op.locales ?? "all");
 			for (const [locale, list] of this.options.messages(key) ?? []) if (op.locales === void 0 || op.locales === "all" || op.locales.includes(locale)) list.forEach((m) => this.deleteMessage(m));
 			const used = this.options.usageMatches({ key }).filter((match) => !match.possible).length;
 			if (used > 0) this.warnings.push(`"${key}" still has ${used} usage${used === 1 ? "" : "s"}.`);
@@ -1827,13 +2075,75 @@ var PlanBuilder = class {
 			}
 		}
 	}
+	/** The review draft, or undefined when reviews are off. */
+	reviewDraft() {
+		const reviews = this.state.reviews;
+		if (reviews) this.draft ??= new ReviewDraft(reviews.data);
+		return this.draft;
+	}
+	requireReviews() {
+		const draft = this.reviewDraft();
+		if (!draft) throw errors.X18N5003({ reason: this.state.reviewProblem ?? "reviews are off" });
+		return draft;
+	}
+	/** Records the source value a target was written against, once the project keeps a review file. */
+	recordSource(key, locale, force = false) {
+		if (locale === this.state.sourceLocale || !force && this.state.reviews?.text === void 0) return;
+		const source = this.plannedSource.has(key) ? this.plannedSource.get(key) : this.options.message(key, this.state.sourceLocale)?.value;
+		if (source !== void 0) this.reviewDraft()?.record(key, locale, sourceHash(source));
+	}
+	review(op) {
+		const draft = this.requireReviews();
+		if (!this.options.messages(op.key)) throw errors.X18N4006({ key: op.key });
+		if (!this.state.locales.includes(op.locale)) throw errors.X18N4008({ reason: `unknown locale "${op.locale}"` });
+		if (op.review === "suggestion" && op.suggestion === void 0) throw errors.X18N4008({ reason: "a suggestion needs a value" });
+		const current = this.options.message(op.key, op.locale)?.value;
+		this.touched.add(op.key);
+		draft.add(op.key, op.locale, {
+			id: op.id,
+			type: op.review,
+			...op.author && { author: op.author },
+			time: op.time,
+			...op.text !== void 0 && { text: op.text },
+			...op.review === "suggestion" && { suggestion: op.suggestion },
+			...op.review === "approve" && current !== void 0 && { value: valueText(current) }
+		});
+	}
+	applySuggestion(id) {
+		const draft = this.requireReviews();
+		const found = findReview(draft.data, id);
+		if (!found) throw errors.X18N5004({ id });
+		const { key, locale, comment } = found;
+		if (comment.type !== "suggestion" || comment.suggestion === void 0 || comment.resolved) throw errors.X18N5005({ id });
+		this.setValue(key, locale, comment.suggestion);
+		this.recordSource(key, locale, true);
+		draft.resolve(id);
+	}
+	resolveReview(id) {
+		const draft = this.requireReviews();
+		const found = findReview(draft.data, id);
+		if (!found) throw errors.X18N5004({ id });
+		this.touched.add(found.key);
+		draft.resolve(id);
+	}
+	markFresh(op) {
+		this.requireReviews();
+		if (this.options.message(op.key, this.state.sourceLocale) === void 0) throw errors.X18N4006({ key: op.key });
+		const locales = op.locales ?? this.state.locales.filter((locale) => this.options.message(op.key, locale) !== void 0);
+		this.touched.add(op.key);
+		for (const locale of locales) this.recordSource(op.key, locale, true);
+	}
+	set(op) {
+		this.setValue(op.key, op.locale, op.value);
+		if (op.locale === this.state.sourceLocale) this.plannedSource.set(op.key, op.value);
+		else if (op.value !== "") this.recordSource(op.key, op.locale);
+		if (!this.config.write.keepFilled) return;
+		for (const locale of this.state.locales) if (locale !== op.locale && !this.state.fallbacks[locale] && !this.options.message(op.key, locale)) this.setValue(op.key, locale, "");
+	}
 	run(ops) {
 		for (const op of ops) switch (op.type) {
 			case "set":
-				this.setValue(op.key, op.locale, op.value);
-				if (this.config.write.keepFilled) {
-					for (const locale of this.state.locales) if (locale !== op.locale && !this.state.fallbacks[locale] && !this.options.message(op.key, locale)) this.setValue(op.key, locale, "");
-				}
+				this.set(op);
 				break;
 			case "delete":
 				this.delete(op);
@@ -1845,7 +2155,19 @@ var PlanBuilder = class {
 			case "extract":
 				this.extract(op.items);
 				break;
-			case "format": for (const s of this.state.resources) if ((!op.paths || op.paths.includes(s.resource.path)) && !s.resource.readonly && !s.error) this.workFor(this.targetOf(s)).formatOnly = true;
+			case "format":
+				for (const s of this.state.resources) if ((!op.paths || op.paths.includes(s.resource.path)) && !s.resource.readonly && !s.error) this.workFor(this.targetOf(s)).formatOnly = true;
+				break;
+			case "review":
+				this.review(op);
+				break;
+			case "resolve-review":
+				this.resolveReview(op.id);
+				break;
+			case "apply-suggestion":
+				this.applySuggestion(op.id);
+				break;
+			case "mark-fresh": this.markFresh(op);
 		}
 	}
 	/** ---- Changes ---- */
@@ -1954,16 +2276,52 @@ var PlanBuilder = class {
 			});
 			texts.set(path, text);
 		}
+		const review = this.reviewChange();
+		if (review) {
+			changes.push(review);
+			texts.set(review.path, this.state.reviews?.text);
+		}
 		return {
 			changes,
 			texts
 		};
 	}
+	reviewChange() {
+		const reviews = this.state.reviews;
+		if (!reviews || !this.draft?.changed) return void 0;
+		const next = reviews.store.serialize(sortReviews(this.draft.data));
+		if (reviews.text === void 0) return {
+			type: "create",
+			path: reviews.file,
+			content: next
+		};
+		return next === reviews.text ? void 0 : {
+			type: "edit",
+			path: reviews.file,
+			edits: diffText(reviews.text, next)
+		};
+	}
 };
 function createPlanner(options) {
 	const texts = /* @__PURE__ */ new Map();
-	function planWith(ops, answers) {
+	/** Gives new reviews an id and a time, so planning again (after decisions) writes the same comments. */
+	function withReviewIds(ops, data) {
+		const used = /* @__PURE__ */ new Set();
+		const time = (/* @__PURE__ */ new Date()).toISOString();
+		return ops.map((op) => {
+			if (op.type !== "review" || op.id !== void 0 && op.time !== void 0) return op;
+			const id = op.id ?? reviewId((id) => used.has(id) || findReview(data, id) !== void 0);
+			used.add(id);
+			return {
+				...op,
+				id,
+				time: op.time ?? time
+			};
+		});
+	}
+	function planWith(input, answers) {
 		const state = options.state();
+		const ops = withReviewIds(input, state.reviews?.data ?? noReviews);
 		const builder = new PlanBuilder(options, state, answers);
 		builder.run(ops);
 		const result = builder.changes();
@@ -2063,7 +2421,8 @@ function buildPrompt(project, kind, to, options, extra) {
 	const from = project.sourceLocale;
 	const match = typeof options.keys === "string" ? keyMatcher([options.keys]) : void 0;
 	const list = Array.isArray(options.keys) ? new Set(options.keys) : void 0;
-	const stale = (key) => isOutdated(project.history(key, from), project.history(key, to));
+	const outdated = new Set(project.analyze().coverage.find((c) => c.locale === to)?.outdated);
+	const stale = (key) => outdated.has(key);
 	const candidates = project.keys({ namespace: options.namespace }).filter((key) => {
 		if (match && !match(key)) return false;
 		if (list && !list.has(key)) return false;
@@ -2118,7 +2477,11 @@ function buildPrompt(project, kind, to, options, extra) {
 		`Write a JSON file \`{ "${to}": { "<key>": "<translation>" } }\` and run \`x18n apply <file> --json\`, or run \`x18n set <key> --locale ${to} --value <text>\` per key.`,
 		`Then run \`x18n check --only placeholder-mismatch,invalid-syntax --locale ${to} --json\` and fix the reported keys.`,
 		nextCursor ? `${candidates.length - end} more keys remain: \`x18n prompt translate --to ${to} --cursor ${nextCursor}\`.` : `To find more work: \`x18n keys --missing ${to} --json --limit 50\`.`
-	] : [`Fix wrong translations with \`x18n set <key> --locale ${to} --value <text>\`, then list what you changed and why.`, `Then run \`x18n check --only placeholder-mismatch,invalid-syntax --locale ${to} --json\`.`];
+	] : project.reviewFile === void 0 ? [`Fix wrong translations with \`x18n set <key> --locale ${to} --value <text>\`, then list what you changed and why.`, `Then run \`x18n check --only placeholder-mismatch,invalid-syntax --locale ${to} --json\`.`] : [
+		`Leave fixes for a human to accept: \`x18n review suggest <key> --locale ${to} --value <text> --text <why>\`. Keep every placeholder in the value.`,
+		`For a problem without a clear fix, run \`x18n review request-change <key> --locale ${to} --text <why>\`.`,
+		`Then list what you reviewed; \`x18n review list --locale ${to} --open\` shows the open reviews.`
+	];
 	return {
 		kind,
 		project: project.name,
@@ -2200,6 +2563,10 @@ function createProject(options) {
 	let usageEligible = () => false;
 	let resourceIndex;
 	let resolved = /* @__PURE__ */ new WeakMap();
+	const reviewFile = config.review.file;
+	let reviewText;
+	let reviewData = noReviews;
+	let reviewError;
 	const normalizers = registry.plugins.flatMap((plugin) => plugin.normalizeKey ? [plugin.normalizeKey] : []);
 	const transforms = registry.plugins.flatMap((plugin) => plugin.transformResource ? [plugin.transformResource] : []);
 	const localeInfoHooks = registry.plugins.flatMap((plugin) => plugin.localeInfo ? [plugin.localeInfo] : []);
@@ -2236,6 +2603,44 @@ function createProject(options) {
 		const form = formOf(key);
 		return !form || categoriesOf(localeInfo(locale), form.type).includes(form.category);
 	}
+	const reviewStore = config.review.enabled ? registry.reviewStores.at(-1) : void 0;
+	async function loadReviews() {
+		if (!reviewStore) return;
+		reviewText = await host.readFile(reviewFile);
+		reviewError = void 0;
+		reviewData = noReviews;
+		if (reviewText === void 0) return;
+		try {
+			reviewData = reviewStore.parse(reviewText);
+		} catch (error) {
+			reviewError = errors.X18N5001({
+				path: reviewFile,
+				reason: error instanceof Error ? error.message : String(error),
+				cause: error
+			});
+		}
+	}
+	/** Reviews the planner may change: none while the file cannot be read, so a write never drops what is in it. */
+	function reviewSource() {
+		return reviewStore && !reviewError ? {
+			store: reviewStore,
+			file: reviewFile,
+			text: reviewText,
+			data: reviewData
+		} : void 0;
+	}
+	function reviewProblem() {
+		return reviewError?.message ?? (config.review.enabled ? "no review store is registered" : "`review.enabled` is false");
+	}
+	function reviews(filter = {}) {
+		return listThreads(reviewData, filter, locales, (key, locale) => message(key, locale)?.value);
+	}
+	/** A target recorded as written against the current source value. */
+	function fresh(key, locale) {
+		const recorded = reviewData.sources[key]?.[locale];
+		const source = message(key, sourceLocale)?.value;
+		return recorded !== void 0 && source !== void 0 && recorded === sourceHash(source);
+	}
 	async function discover() {
 		const ctx = {
 			host,
@@ -2692,7 +3097,10 @@ function createProject(options) {
 				error: s.error,
 				path
 			}] : []),
-			discoveryErrors,
+			discoveryErrors: [...discoveryErrors, ...reviewError ? [{
+				error: reviewError,
+				path: reviewFile
+			}] : []],
 			messages: idx().messages,
 			parents: idx().parents,
 			usages: idx().usages,
@@ -2700,7 +3108,9 @@ function createProject(options) {
 			prefixUsages: idx().prefixUsages,
 			derived: idx().derived,
 			files,
-			history: history.get
+			history: history.get,
+			fresh,
+			reviews
 		}),
 		basesOf,
 		formOf,
@@ -2726,6 +3136,29 @@ function createProject(options) {
 		}
 		return list.sort();
 	}
+	function search(query, options = {}) {
+		if (!query) return [];
+		const lower = query.toLowerCase();
+		const score = (value) => !options.exact || value.toLowerCase().includes(lower) ? fuzzyScore(query, value) : -1;
+		const found = [];
+		for (const key of idx().messages.keys()) {
+			let best;
+			for (const locale of locales) {
+				const leaf = message(key, locale)?.value;
+				if (leaf === void 0 || leaf === null) continue;
+				const value = String(leaf);
+				const s = score(value);
+				if (s >= 0 && (!best || s > best.score)) best = {
+					key,
+					locale,
+					value,
+					score: s
+				};
+			}
+			if (best) found.push(best);
+		}
+		return found.sort((a, b) => b.score - a.score || a.value.length - b.value.length || a.key.localeCompare(b.key));
+	}
 	function get(key) {
 		const { messages, keyPaths } = idx();
 		const byLocale = messages.get(key);
@@ -2739,7 +3172,8 @@ function createProject(options) {
 			messages: list,
 			missing: locales.filter((locale) => !byLocale.has(locale) && needs(key, locale)),
 			usages: usageMatches({ key }),
-			diagnostics: analyzer.analyze().diagnostics.filter((d) => d.key === key)
+			diagnostics: analyzer.analyze().diagnostics.filter((d) => d.key === key),
+			reviews: reviews({ key })
 		};
 	}
 	function keyAt(path, offset) {
@@ -2793,6 +3227,10 @@ function createProject(options) {
 			conflicts: registry.conflicts,
 			errors: [
 				...discoveryErrors,
+				...reviewError ? [{
+					error: reviewError,
+					path: reviewFile
+				}] : [],
 				...resources.flatMap((state) => state.error ? [{
 					error: state.error,
 					path: state.resource.path
@@ -2822,14 +3260,22 @@ function createProject(options) {
 		collect(idx());
 		return [...out];
 	}
+	/** Reloads the review file and returns the keys whose reviews or records it had or has. */
+	async function reloadReviews() {
+		const keysOf = (data) => [...Object.keys(data.threads), ...Object.keys(data.sources)];
+		const old = keysOf(reviewData);
+		await loadReviews();
+		return [...old, ...keysOf(reviewData)];
+	}
 	let current = Promise.resolve();
 	async function update(events) {
 		const run = current.then(async () => {
 			if (events.length === 0) return void 0;
 			const before = idx();
 			const paths = new Set(events.map((event) => event.path));
+			const reviewKeys = paths.has(reviewFile) ? await reloadReviews() : [];
 			const resourcePaths = new Set([...resourceStates.values()].map((state) => state.resource.path));
-			const maybeResource = (path) => !resourcePaths.has(path) && registry.formatIdFor(path) !== void 0 && !usageEligible(path);
+			const maybeResource = (path) => path !== reviewFile && !resourcePaths.has(path) && registry.formatIdFor(path) !== void 0 && !usageEligible(path);
 			const blockPaths = new Set([...resourceStates.values()].filter((state) => state.resource.block).map((state) => state.resource.path));
 			const structural = events.some((event) => event.type !== "change" || maybeResource(event.path) || blockPaths.has(event.path));
 			if (structural || [...paths].some((path) => resourcePaths.has(path))) await loadResources(structural ? await discover() : [...resourceStates.values()].map((state) => ({
@@ -2843,7 +3289,7 @@ function createProject(options) {
 			const change = {
 				revision,
 				paths: [...paths],
-				keys: touchedKeys(paths, before)
+				keys: [.../* @__PURE__ */ new Set([...touchedKeys(paths, before), ...reviewKeys])]
 			};
 			emit(change);
 			return change;
@@ -2862,7 +3308,9 @@ function createProject(options) {
 			fallbacks,
 			namespaced,
 			resources: [...resourceStates.values()],
-			fileTexts
+			fileTexts,
+			reviews: reviewSource(),
+			reviewProblem: reviewProblem()
 		}),
 		message: (key, locale) => message(key, locale),
 		messages: (key) => idx().messages.get(key),
@@ -2876,7 +3324,8 @@ function createProject(options) {
 		update
 	});
 	const ready = (async () => {
-		await loadResources(await discover(), "all");
+		const candidates = await discover();
+		await Promise.all([loadResources(candidates, "all"), loadReviews()]);
 		await scanAll();
 		revision++;
 	})();
@@ -2905,6 +3354,7 @@ function createProject(options) {
 		placeholderSyntaxes: registry.placeholders,
 		extractTemplates: [...(config.extract.templates ?? []).map((template) => typeof template === "string" ? { template } : template), ...registry.extractors.flatMap((extractor) => extractor.templates)],
 		keys,
+		search,
 		get,
 		message,
 		parseKey(input) {
@@ -2947,13 +3397,18 @@ function createProject(options) {
 		},
 		history: history.get,
 		valueAt: history.valueAt,
+		reviews,
+		reviewFile: reviewStore && reviewFile,
+		async reviewAuthor() {
+			return config.review.author ?? await host.identity?.();
+		},
 		prompt: (kind, locale, promptOptions = {}) => buildPrompt(project, kind, locale, promptOptions, {
 			config,
 			hooks: registry.plugins.flatMap((plugin) => plugin.translatePrompt ? [plugin.translatePrompt] : [])
 		}),
 		explain,
 		localeInfo,
-		text: (path) => fileTexts.get(path) ?? files.get(path)?.text,
+		text: (path) => fileTexts.get(path) ?? files.get(path)?.text ?? (path === reviewFile ? reviewText : void 0),
 		owns: (path) => fileTexts.has(path) || files.has(path) || usageEligible(path),
 		plan: (ops) => planner.plan(ops),
 		apply: (plan, applyOptions) => planner.apply(plan, applyOptions?.answers ?? {}),
@@ -3027,6 +3482,11 @@ function defaultDraft() {
 		ignoreKeys: [],
 		glossary: [],
 		history: { providers: [] },
+		review: {
+			enabled: true,
+			file: ".x18n/reviews.yml",
+			author: void 0
+		},
 		pluginConfigs: {}
 	};
 }
@@ -3154,6 +3614,14 @@ function applyLayer(draft, layer, origin, origins) {
 		};
 		mark("history");
 	}
+	if (layer.review !== void 0) {
+		draft.review = {
+			enabled: layer.review.enabled ?? draft.review.enabled,
+			file: layer.review.file ?? draft.review.file,
+			author: layer.review.author ?? draft.review.author
+		};
+		mark("review");
+	}
 	if (layer.pluginConfigs !== void 0) {
 		draft.pluginConfigs = {
 			...draft.pluginConfigs,
@@ -3311,4 +3779,4 @@ async function resolveConfig(options) {
 	};
 }
 //#endregion
-export { ConfigSchema, PluginFileSchema, applyMessageOps, applyTextEdits, buildTree, contractVersion, createLibraryPlugin, createLineIndex, createMemoryHost, createOverlayHost, createPlaceholderComparer, createProject, createRegistry, defineConfig, definePlugin, definePreset, diffText, envelope, errors, extensionOf, globToRegExp, hashText, isJsonObject, isKeyUnder, isMessageLeaf, isMessageTree, isPreset, isX18nError, joinKey, keyMatcher, localeSpellingKey, parseLocaleInfo, parseMessageBatch, pathId, pathMatcher, placeholderProblems, rangeContains, renderPrompt, replaceKeyPrefix, resolveConfig, sortTree, splitKey, toErrorInfo, toWireDiagnostic, toWireRange, validate, walkLeaves };
+export { ConfigSchema, PluginFileSchema, ReviewFileSchema, applyMessageOps, applyTextEdits, buildTree, contractVersion, createLibraryPlugin, createLineIndex, createMemoryHost, createOverlayHost, createPlaceholderComparer, createProject, createRegistry, defineConfig, definePlugin, definePreset, diffText, envelope, errors, extensionOf, fuzzyScore, globToRegExp, hashText, isJsonObject, isKeyUnder, isMessageLeaf, isMessageTree, isPreset, isX18nError, joinKey, keyMatcher, localeSpellingKey, parseLocaleInfo, parseMessageBatch, pathId, pathMatcher, placeholderProblems, rangeContains, renderExplanation, renderPrompt, replaceKeyPrefix, resolveConfig, sortTree, splitKey, toErrorInfo, toWireDiagnostic, toWireRange, validate, walkLeaves };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/core",
   "type": "module",
-  "version": "0.0.14",
+  "version": "0.1.0",
   "description": "Runtime-neutral engine of x18n: domain model, plugin API and project analysis",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",

package/schema/config.json

@@ -591,6 +591,32 @@
         }
       ]
     },
+    "review": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "file": {
+          "type": "string"
+        },
+        "author": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "email": {
+              "type": "string"
+            }
+          },
+          "required": [],
+          "additionalProperties": false
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    },
     "projects": {
       "type": "array",
       "items": {

package/schema/reviews.json

@@ -0,0 +1,98 @@
+{
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "x18n": {
+      "const": 1
+    },
+    "threads": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "propertyNames": {
+          "type": "string"
+        },
+        "additionalProperties": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "type": {
+                "enum": [
+                  "comment",
+                  "approve",
+                  "request-change",
+                  "suggestion"
+                ],
+                "type": "string"
+              },
+              "author": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "email": {
+                    "type": "string"
+                  }
+                },
+                "required": [],
+                "additionalProperties": false
+              },
+              "time": {
+                "type": "string"
+              },
+              "text": {
+                "type": "string"
+              },
+              "suggestion": {
+                "type": "string"
+              },
+              "value": {
+                "type": "string"
+              },
+              "resolved": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "id",
+              "type",
+              "time"
+            ],
+            "additionalProperties": false
+          }
+        }
+      }
+    },
+    "sources": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "propertyNames": {
+          "type": "string"
+        },
+        "additionalProperties": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required": [
+    "x18n"
+  ],
+  "additionalProperties": false,
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "x18n reviews"
+}