@x18n/core 0.1.7 → 0.1.9

package/dist/index.d.mts

@@ -336,6 +336,21 @@ interface LocaleFinder {
     readonly namespace: string | undefined;
     readonly model: Resource | undefined;
   }, ctx: FinderContext) => string | undefined) | undefined;
+  /**
+   * A file of its own for one key in a locale, for layouts with one file per message. A new message of the key goes
+   * there, created with `format` (default: by extension) when it does not exist; a rename moves the message to the
+   * file of the new key; a delete that leaves the file empty deletes it.
+   */
+  readonly resolveKey?: ((target: {
+    readonly key: KeyString;
+    readonly locale: LocaleCode;
+  }, ctx: FinderContext) => KeyFile | undefined) | undefined;
+}
+/** The file of one key, from a locale finder's `resolveKey`. */
+interface KeyFile {
+  readonly path: string;
+  /** Format id of a new file. Default: the format of its extension. */
+  readonly format?: string | undefined;
 }
 interface FormatContext {
   readonly path: string;
@@ -349,6 +364,10 @@ interface ParseResult {
   readonly ranges?: ReadonlyMap<string, NodeRange> | undefined;
   /** What the file says about a message for translators (a note or comment next to it), keyed by `pathId(storedPath)`. */
   readonly descriptions?: ReadonlyMap<string, string> | undefined;
+  /** The translation state the file records for a message (XLIFF `state`, PO `fuzzy`), keyed by `pathId(storedPath)`. */
+  readonly states?: ReadonlyMap<string, MessageState> | undefined;
+  /** Display labels of keys that do not read well, such as hashes, keyed by `pathId(storedPath)`. */
+  readonly labels?: ReadonlyMap<string, string> | undefined;
 }
 type MessageOp = {
   readonly type: "set";
@@ -480,6 +499,10 @@ interface LocaleCoverage {
   readonly empty: readonly KeyString[];
   /** Translated keys whose message last changed before the source message. */
   readonly outdated: readonly KeyString[];
+  /** Translated keys that the format marks `needs-review`. */
+  readonly needsReview: readonly KeyString[];
+  /** Translated keys that the format marks `reviewed`. */
+  readonly reviewed: readonly KeyString[];
 }
 /** When a message last changed, as a history provider knows it. */
 interface MessageChange {
@@ -627,6 +650,29 @@ interface ResourceTransform {
   /** Descriptions that the stored tree holds beside the messages, such as `{ "name": { "message": "...", "description": "..." } }`, keyed by `pathId(storedPath)`. */
   readonly describe?: ((tree: MessageTree, ctx: ResourceTransformContext) => ReadonlyMap<string, string>) | undefined;
 }
+/** A review edit of a plan, after it is applied to the review data. */
+interface ReviewEdit {
+  /** The review type of a new comment, or the op that resolved or applied one. */
+  readonly type: ReviewType | "resolve-review" | "apply-suggestion";
+  readonly key: KeyString;
+  readonly locale: LocaleCode;
+  /** The new comment, or the comment that was resolved or applied. */
+  readonly comment: ReviewComment;
+  /** The thread of the message after the edit, oldest first. */
+  readonly comments: readonly ReviewComment[];
+}
+interface ReviewEditContext {
+  /** A message before the plan. */
+  readonly message: (key: KeyString, locale: LocaleCode) => Message | undefined;
+  readonly resource: (id: ResourceId) => Resource | undefined;
+  /** The text of a project file as the plan leaves it so far, including earlier writes of `reviewEdit` hooks. */
+  readonly text: (path: string) => string | undefined;
+}
+/** The full new content of a file, which core puts into the plan. */
+interface FileWrite {
+  readonly path: string;
+  readonly content: string;
+}
 interface PromptDraft {
   readonly rules: string[];
   readonly notes: string[];
@@ -665,6 +711,8 @@ interface Plugin {
   readonly derivedKeys?: readonly string[] | undefined;
   readonly transformResource?: ResourceTransform | undefined;
   readonly translatePrompt?: ((draft: PromptDraft, ctx: PromptContext) => void) | undefined;
+  /** Called for each review edit of a plan, in op order. The writes it returns go into the same plan. */
+  readonly reviewEdit?: ((edit: ReviewEdit, ctx: ReviewEditContext) => readonly FileWrite[] | undefined) | undefined;
   /** Display data for a locale code. The first plugin that returns a value wins. */
   readonly localeInfo?: ((code: LocaleCode) => Partial<LocaleInfo> | undefined) | undefined;
 }
@@ -775,11 +823,15 @@ interface GlossaryEntry {
   readonly translations?: {
     readonly [locale: string]: string;
   } | undefined;
+  /** Other forms per locale, matched at the start of a word: inflections and compound stems of the translation, or of the term under the source locale. */
+  readonly forms?: {
+    readonly [locale: string]: readonly string[];
+  } | undefined;
   readonly note?: string | undefined;
   readonly doNotTranslate?: boolean | undefined;
 }
 interface ExtractTemplate {
-  /** Replacement code with `{key}`, `{attr}`, `{args}`, `{text}`, `{source}` and `{parts}` tokens. `{key}` and `{text}` are escaped for the quotes around them. */
+  /** Replacement code. `{key}` is the key, `{attr}` the attribute name, `{args}` the arguments of a template string, `{text}` the message of the hard string, for a default value, `{source}` the text as written in the file, and `{parts}` the message as the body of a template string. `{key}` and `{text}` are escaped for the quotes around them. */
   readonly template: string;
   /** Hard-string kinds the template applies to, for example `jsx-text`. */
   readonly kinds?: readonly string[] | undefined;
@@ -813,6 +865,8 @@ interface ExtractOptions {
 interface UsageOptions {
   readonly include?: readonly string[] | undefined;
   readonly exclude?: readonly string[] | undefined;
+  /** Skip the files that `.gitignore` files ignore. Default `true`. Set `false` to scan a checkout that git ignores, such as a clone of the sources in a translations repository. */
+  readonly gitignore?: boolean | undefined;
   readonly calls?: readonly CallSpec[] | undefined;
   readonly regex?: readonly RegexScannerSpec[] | undefined;
   /** Callee names never counted as translate calls. */
@@ -888,7 +942,7 @@ interface SerializableConfig {
   } | undefined;
   /** Turn every warning into an error. */
   readonly strict?: boolean | undefined;
-  /** Keys (globs) excluded from all checks. */
+  /** Keys (globs) excluded from all checks. `x18n.config.ts` also takes regular expressions. */
   readonly ignoreKeys?: readonly string[] | undefined;
   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`). */
@@ -911,9 +965,13 @@ interface HistorySettings extends HistoryOptions {
 }
 type PresetOption = Preset | PluginSpecifier | false | undefined;
 type PluginOption = Plugin | Preset | PluginSpecifier | false | undefined;
+/** A key glob (`*` inside a segment, `**` across segments), or a regular expression tested against the whole key. */
+type KeyPattern = string | RegExp;
 /** The config accepted by `defineConfig`: the serializable part plus plugin objects. */
-interface UserConfig extends Omit<SerializableConfig, "presets" | "plugins" | "checks" | "history"> {
+interface UserConfig extends Omit<SerializableConfig, "presets" | "plugins" | "checks" | "history" | "ignoreKeys"> {
   readonly presets?: "auto" | readonly PresetOption[] | undefined;
+  /** Keys excluded from all checks: globs, or regular expressions tested against the whole key (`ns:a.b` when namespaced). */
+  readonly ignoreKeys?: readonly KeyPattern[] | undefined;
   /** History providers for stale translations: `false` turns them off; provider options such as `git` sit under their key; `providers` adds providers asked first. */
   readonly history?: boolean | (HistoryOptions & {
     readonly providers?: readonly HistoryProvider[] | undefined;
@@ -952,6 +1010,7 @@ interface ResolvedConfig {
   readonly usage: {
     readonly include: readonly string[];
     readonly exclude: readonly string[];
+    readonly gitignore: boolean;
     readonly calls: readonly CallSpec[];
     readonly regex: readonly RegexScannerSpec[];
     readonly ignoreCallees: readonly string[];
@@ -968,7 +1027,7 @@ interface ResolvedConfig {
     readonly [checkId: string]: CheckSetting;
   };
   readonly strict: boolean;
-  readonly ignoreKeys: readonly string[];
+  readonly ignoreKeys: readonly KeyPattern[];
   readonly glossary: readonly GlossaryEntry[];
   readonly history: false | HistorySettings;
   readonly review: {
@@ -1051,6 +1110,8 @@ interface Resource {
   /** Key separator of the resource when it differs from the config's `keySeparator` (from its resource spec). */
   readonly keySeparator?: KeySeparator | undefined;
 }
+/** How far a translation got, as in XLIFF: a value can exist before anyone reviews it. */
+type MessageState = "translated" | "needs-review" | "reviewed";
 /** One stored value of one key in one locale. */
 interface Message {
   readonly key: KeyString;
@@ -1063,6 +1124,10 @@ interface Message {
   readonly range: NodeRange | undefined;
   /** What the resource says about the message for translators, such as a note or a comment beside it. */
   readonly description?: string | undefined;
+  /** The translation state the resource records, such as XLIFF `state` or PO `fuzzy`. */
+  readonly state?: MessageState | undefined;
+  /** A display label of the key from the resource, for keys that do not read well, such as hashes. */
+  readonly label?: string | undefined;
 }
 type UsageKind = "call" | "selector" | "accessor" | "constant" | "marker";
 interface Usage {
@@ -1247,8 +1312,11 @@ export declare function replaceKeyPrefix(key: KeyString, from: KeyString, to: Ke
  * `{a,b}` alternates, `[...]` is a character class.
  */
 export declare function globToRegExp(glob: string, separator?: string): RegExp;
-/** Matcher over key globs: `*` stays inside a segment, `**` spans segments. With literal keys (`separator: false`) `*` spans the whole key. */
-export declare function keyMatcher(globs: readonly string[], separator?: KeySeparator): (key: KeyString) => boolean;
+/**
+ * Matcher over key patterns. In a glob `*` stays inside a segment and `**` spans segments; with literal keys
+ * (`separator: false`) `*` spans the whole key. A regular expression is tested against the whole key as is.
+ */
+export declare function keyMatcher(patterns: readonly KeyPattern[], separator?: KeySeparator): (key: KeyString) => boolean;
 /** Matcher over posix file paths. */
 export declare function pathMatcher(globs: readonly string[]): (path: string) => boolean;
 //#endregion
@@ -1523,6 +1591,8 @@ interface KeyInfo {
   readonly key: KeyString;
   readonly namespace: string | undefined;
   readonly path: readonly string[];
+  /** Display label of the key: the first `label` of its messages, source locale first. */
+  readonly label: string | undefined;
   /** One message per locale that has the key, source locale first. */
   readonly messages: readonly Message[];
   readonly missing: readonly LocaleCode[];
@@ -1876,4 +1946,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, BaselineSummary, 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, KeptUnusedKey, KeyContext, KeyId, KeyInfo, KeyQuery, KeySeparator, 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, ParamsSource, 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, PromptIssue, PromptItem, PromptOptions, RegexScannerSpec, RelatedValue, 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, UnusedDeletion, UnusedKeyDeletion, UnusedQuery, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };
+export type { Analysis, Answers, ApplyResult, ArgSource, BaselineSummary, 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, FileWrite, FinderContext, Fix, Format, FormatContext, FormatEntry, GlobOptions, GlossaryEntry, HardString, HistoryConfigs, HistoryContext, HistoryOptions, HistoryProvider, HistorySettings, Host, JsonObject, JsonPrimitive, JsonValue, KeptUnusedKey, KeyContext, KeyFile, KeyId, KeyInfo, KeyPattern, KeyQuery, KeySeparator, KeyString, KeyTarget, LazyFormat, LazyScanner, LibraryOptions, LineIndex, LinePosition, LocaleCode, LocaleCoverage, LocaleFinder, LocaleInfo, Location, Logger, ManifestReader, MemoryHost, Message, MessageChange, MessageHistory, MessageLeaf, MessageOp, MessageState, MessageTree, NamespaceFromPath, NamespaceOptions, NodeRange, OverlayHost, ParamsSource, 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, PromptIssue, PromptItem, PromptOptions, RegexScannerSpec, RelatedValue, ReportInput, ReportSummary, Reporter, ReporterContext, ReporterLoader, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ReviewAuthor, ReviewComment, ReviewData, ReviewEdit, ReviewEditContext, ReviewFile, ReviewFilter, ReviewOptions, ReviewState, ReviewStore, ReviewThread, ReviewType, ScanContext, ScanResult, Scanner, ScannerEntry, SchemaIssue, Scope, SearchMatch, SearchOptions, SerializableConfig, Setup, Severity, SourceFile, TextEdit, TextRange, ThreadComment, TreeLeaf, UnusedDeletion, UnusedKeyDeletion, UnusedQuery, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };

package/dist/index.mjs

@@ -379,10 +379,13 @@ function globToRegExp(glob, separator = "/") {
 	}
 	return new RegExp(`^${out}$`);
 }
-/** Matcher over key globs: `*` stays inside a segment, `**` spans segments. With literal keys (`separator: false`) `*` spans the whole key. */
-function keyMatcher(globs, separator = ".") {
-	if (globs.length === 0) return () => false;
-	const regexes = globs.map((glob) => globToRegExp(glob, separator === false ? "\0" : separator));
+/**
+* Matcher over key patterns. In a glob `*` stays inside a segment and `**` spans segments; with literal keys
+* (`separator: false`) `*` spans the whole key. A regular expression is tested against the whole key as is.
+*/
+function keyMatcher(patterns, separator = ".") {
+	if (patterns.length === 0) return () => false;
+	const regexes = patterns.map((pattern) => pattern instanceof RegExp ? new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, "")) : globToRegExp(pattern, separator === false ? "\0" : separator));
 	return (key) => regexes.some((re) => re.test(key));
 }
 /** Matcher over posix file paths. */
@@ -621,11 +624,15 @@ function deleteIn(tree, path) {
 		delete parents[i - 1][path[i - 1]];
 	}
 }
+/** Applies ops to the tree itself. Parent objects left empty are removed. */
+function applyMessageOpsInPlace(tree, ops) {
+	for (const op of ops) if (op.type === "set") setIn(tree, op.path, op.value);
+	else deleteIn(tree, op.path);
+}
 /** Applies ops to a copy of the tree. Parent objects left empty are removed. */
 function applyMessageOps(tree, ops) {
 	const out = cloneTree(tree);
-	for (const op of ops) if (op.type === "set") setIn(out, op.path, op.value);
-	else deleteIn(out, op.path);
+	applyMessageOpsInPlace(out, ops);
 	return out;
 }
 /** Sorts keys at every level. */
@@ -882,6 +889,7 @@ const extractOptions = v.strictObject({
 const glossaryEntry = v.strictObject({
 	term: v.string(),
 	translations: v.optional(v.record(v.string(), v.string())),
+	forms: v.optional(v.record(v.string(), v.array(v.string()))),
 	note: v.optional(v.string()),
 	doNotTranslate: v.optional(v.boolean())
 });
@@ -924,6 +932,7 @@ const ConfigSchema = v.strictObject({
 	usage: v.optional(v.strictObject({
 		include: v.optional(strings),
 		exclude: v.optional(strings),
+		gitignore: v.optional(v.boolean()),
 		calls: v.optional(v.array(callSpec)),
 		regex: v.optional(v.array(regexSpec)),
 		ignoreCallees: v.optional(strings),
@@ -1370,12 +1379,19 @@ function computeCoverage(state, options, sourceKeys) {
 		const missing = [];
 		const empty = [];
 		const outdated = [];
+		const needsReview = [];
+		const reviewed = [];
 		for (const key of reference) {
-			const value = messages.get(key)?.get(locale)?.[0]?.value;
+			const message = messages.get(key)?.get(locale)?.[0];
+			const value = message?.value;
 			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)) && !state.fresh(key, locale)) outdated.push(key);
+				continue;
+			}
+			if (locale !== sourceLocale && isOutdated(state.history(key, sourceLocale), state.history(key, locale)) && !state.fresh(key, locale)) outdated.push(key);
+			if (message?.state === "needs-review") needsReview.push(key);
+			else if (message?.state === "reviewed") reviewed.push(key);
 		}
 		return {
 			locale,
@@ -1383,7 +1399,9 @@ function computeCoverage(state, options, sourceKeys) {
 			translated: reference.length - missing.length - empty.length,
 			missing,
 			empty,
-			outdated
+			outdated,
+			needsReview,
+			reviewed
 		};
 	});
 }
@@ -1725,6 +1743,10 @@ function nodeAt(tree, path) {
 	}
 	return node;
 }
+function leafAt(tree, path) {
+	const node = nodeAt(tree, path);
+	return isMessageLeaf(node) ? node : void 0;
+}
 /** True for flat files (`{ "a.b": "x" }`), false for nested ones, undefined when it cannot tell. */
 function isFlatTree(tree, separator) {
 	const entries = Object.entries(tree);
@@ -1771,6 +1793,10 @@ var PlanBuilder = class {
 	answers;
 	work = /* @__PURE__ */ new Map();
 	created = /* @__PURE__ */ new Map();
+	/** New files that a finder's `resolveKey` gave one key. */
+	keyFiles = /* @__PURE__ */ new Map();
+	/** Resources that are the file of a key deleted from them: removed once empty. */
+	keyFilesLeft = /* @__PURE__ */ new Set();
 	sourceEdits = /* @__PURE__ */ new Map();
 	sourceImports = /* @__PURE__ */ new Map();
 	decisions = [];
@@ -1780,6 +1806,7 @@ var PlanBuilder = class {
 	config;
 	/** Source values set by this plan, for the source records of targets set after them. */
 	plannedSource = /* @__PURE__ */ new Map();
+	reviewEdits = [];
 	draft;
 	constructor(options, state, answers) {
 		this.options = options;
@@ -1807,7 +1834,7 @@ var PlanBuilder = class {
 		if (!entry) {
 			entry = {
 				target,
-				tree: target.state?.rawTree ?? {},
+				tree: cloneTree(target.state?.rawTree ?? {}),
 				ops: [],
 				keyRenames: [],
 				formatOnly: false
@@ -1851,7 +1878,8 @@ var PlanBuilder = class {
 		const stored = this.options.toStored(entry.target, relative);
 		const separator = this.separatorOf(entry.target);
 		if (separator === false) return stored;
-		return stored.length === relative.length && (isFlatTree(entry.tree, separator) ?? this.config.keyStyle === "flat") ? [stored.join(separator)] : stored;
+		if (stored.length === relative.length) entry.flat ??= isFlatTree(entry.tree, separator);
+		return stored.length === relative.length && (entry.flat ?? this.config.keyStyle === "flat") ? [stored.join(separator)] : stored;
 	}
 	createTarget(key, locale) {
 		const { resources, sourceLocale, namespaced } = this.state;
@@ -1898,8 +1926,40 @@ var PlanBuilder = class {
 		this.created.set(path, target);
 		return target;
 	}
-	/** Placement: the namespace's resource, then the longest shared prefix, then the first; a tie is a decision. */
+	/** The file a locale finder gives the key, created when it does not exist. */
+	keyTarget(key, locale) {
+		const file = this.options.resolveKey(key, locale);
+		if (!file) return void 0;
+		const existing = this.state.resources.find((s) => s.resource.path === file.path && !s.resource.block);
+		if (existing) {
+			if (existing.resource.locale !== locale || this.relativePath(key, existing.resource) === void 0) throw errors.X18N4005({
+				key,
+				locale
+			});
+			return this.targetOf(existing);
+		}
+		const pending = this.keyFiles.get(file.path);
+		if (pending) return pending;
+		const format = file.format === void 0 ? this.options.registry.formatFor(file.path) : this.options.registry.formatById(file.format);
+		if (!format?.serialize) throw errors.X18N4005({
+			key,
+			locale
+		});
+		const target = {
+			id: file.path,
+			path: file.path,
+			locale,
+			namespace: this.state.namespaced ? this.keyId(key).namespace ?? this.config.namespace.default : void 0,
+			format,
+			state: void 0
+		};
+		this.keyFiles.set(file.path, target);
+		return target;
+	}
+	/** Placement: the key's own file, then the namespace's resource, then the longest shared prefix, then the first; a tie is a decision. */
 	pickTarget(key, locale) {
+		const own = this.keyTarget(key, locale);
+		if (own) return own;
 		let inLocale = this.state.resources.filter((s) => s.resource.locale === locale && this.relativePath(key, s.resource) !== void 0);
 		const source = this.options.message(key, this.state.sourceLocale);
 		const sourceNamespace = source && this.stateById.get(source.resource)?.resource.namespace;
@@ -1932,18 +1992,30 @@ var PlanBuilder = class {
 	/** ---- Message ops ---- */
 	pushOp(entry, op) {
 		entry.ops.push(op);
-		entry.tree = applyMessageOps(entry.tree, [op]);
+		this.applyOps(entry, [op]);
+	}
+	/** Applies ops to the entry's tree in place; drops `flat` when a top-level object appears or goes, or a top-level key goes. */
+	applyOps(entry, ops) {
+		for (const op of ops) {
+			const top = op.path[0];
+			const before = entry.tree[top];
+			applyMessageOpsInPlace(entry.tree, [op]);
+			const after = entry.tree[top];
+			if ((before !== void 0 && !isMessageLeaf(before)) !== (after !== void 0 && !isMessageLeaf(after)) || before !== void 0 && after === void 0) entry.flat = void 0;
+		}
 	}
 	setValue(key, locale, value) {
 		this.touched.add(key);
 		const existing = this.options.message(key, locale);
 		if (existing) {
-			this.pushOp(this.workFor(this.targetOf(this.writable(existing.resource))), {
+			const entry = this.workFor(this.targetOf(this.writable(existing.resource)));
+			const before = leafAt(entry.tree, existing.storedPath);
+			this.pushOp(entry, {
 				type: "set",
 				path: existing.storedPath,
 				value
 			});
-			return;
+			return before;
 		}
 		const target = this.pickTarget(key, locale);
 		if (target.state) this.writable(target.state.resource.id);
@@ -1956,9 +2028,12 @@ var PlanBuilder = class {
 			path: stored,
 			value
 		});
+		return isMessageLeaf(occupied) ? occupied : void 0;
 	}
 	deleteMessage(m) {
-		const entry = this.workFor(this.targetOf(this.writable(m.resource)));
+		const s = this.writable(m.resource);
+		if (!s.resource.block && this.options.resolveKey(m.key, m.locale)?.path === s.resource.path) this.keyFilesLeft.add(s.resource.id);
+		const entry = this.workFor(this.targetOf(s));
 		let path = [...m.storedPath];
 		while (path.length > 1) {
 			const parent = nodeAt(entry.tree, path.slice(0, -1));
@@ -1997,7 +2072,7 @@ var PlanBuilder = class {
 				text: last
 			});
 			const leaves = [...walkLeaves(node, stored)];
-			entry.tree = applyMessageOps(entry.tree, [...leaves.map((leaf) => ({
+			this.applyOps(entry, [...leaves.map((leaf) => ({
 				type: "delete",
 				path: leaf.path
 			})), ...leaves.map((leaf) => ({
@@ -2012,44 +2087,54 @@ var PlanBuilder = class {
 	moveKey(from, to, renamed = /* @__PURE__ */ new Set()) {
 		this.touched.add(from);
 		this.touched.add(to);
-		for (const [locale, list] of this.options.messages(from) ?? []) {
-			const m = list[0];
+		for (const list of this.options.messages(from)?.values() ?? []) for (const m of [...list].reverse()) {
 			if (renamed.has(m.resource)) continue;
-			const s = this.writable(m.resource);
-			const relative = this.relativePath(to, s.resource);
-			if (!relative) {
-				this.deleteMessage(m);
-				this.setValue(to, locale, m.value);
-				continue;
-			}
-			const entry = this.workFor(this.targetOf(s));
-			const separator = this.separatorOf(s.resource);
-			const flat = separator !== false && m.storedPath.length === 1 && m.storedPath[0].includes(separator);
-			const next = flat ? [relative.join(separator)] : this.options.toStored(s.resource, relative);
-			const sameParent = next.length === m.storedPath.length && next.slice(0, -1).every((segment, i) => segment === m.storedPath[i]);
-			const last = next.at(-1);
-			if (sameParent && m.range && (flat ? safeFlat : safeSegment).test(last)) {
-				entry.keyRenames.push({
-					range: m.range.key,
-					text: last
-				});
-				entry.tree = applyMessageOps(entry.tree, [{
-					type: "delete",
-					path: m.storedPath
-				}, {
-					type: "set",
-					path: next,
-					value: m.value
-				}]);
-				continue;
+			const replaced = this.moveMessage(m, to);
+			if (replaced !== void 0 && replaced !== m.value) {
+				const path = this.stateById.get(m.resource)?.resource.path ?? m.resource;
+				this.warnings.push(`Copies of "${from}" in ${m.locale} have different values; "${to}" keeps the one from ${path}.`);
 			}
+		}
+	}
+	moveMessage(m, to) {
+		const s = this.writable(m.resource);
+		const relative = this.relativePath(to, s.resource);
+		const own = this.options.resolveKey(to, m.locale);
+		if (!relative || own && own.path !== s.resource.path) {
 			this.deleteMessage(m);
-			this.pushOp(entry, {
+			return this.setValue(to, m.locale, m.value);
+		}
+		const entry = this.workFor(this.targetOf(s));
+		const separator = this.separatorOf(s.resource);
+		const flat = separator !== false && m.storedPath.length === 1 && m.storedPath[0].includes(separator);
+		const next = flat ? [relative.join(separator)] : this.options.toStored(s.resource, relative);
+		const sameParent = next.length === m.storedPath.length && next.slice(0, -1).every((segment, i) => segment === m.storedPath[i]);
+		const last = next.at(-1);
+		if (sameParent && m.range && (flat ? safeFlat : safeSegment).test(last)) {
+			const replaced = leafAt(entry.tree, next);
+			entry.keyRenames.push({
+				range: m.range.key,
+				text: last
+			});
+			this.applyOps(entry, [{
+				type: "delete",
+				path: m.storedPath
+			}, {
 				type: "set",
-				path: this.storedPathFor(entry, relative),
+				path: next,
 				value: m.value
-			});
+			}]);
+			return replaced;
 		}
+		this.deleteMessage(m);
+		const path = this.storedPathFor(entry, relative);
+		const replaced = leafAt(entry.tree, path);
+		this.pushOp(entry, {
+			type: "set",
+			path,
+			value: m.value
+		});
+		return replaced;
 	}
 	/** The raw text a usage needs to refer to `next`, given its scope. */
 	rawFor(usage, next) {
@@ -2189,6 +2274,17 @@ var PlanBuilder = class {
 			...op.review === "suggestion" && { suggestion: op.suggestion },
 			...op.review === "approve" && current !== void 0 && { value: valueText(current) }
 		});
+		this.reviewEdited(draft, op.review, op.id);
+	}
+	reviewEdited(draft, type, id) {
+		const { key, locale, comment } = findReview(draft.data, id);
+		this.reviewEdits.push({
+			type,
+			key,
+			locale,
+			comment,
+			comments: draft.data.threads[key][locale]
+		});
 	}
 	applySuggestion(id) {
 		const draft = this.requireReviews();
@@ -2199,6 +2295,7 @@ var PlanBuilder = class {
 		this.setValue(key, locale, comment.suggestion);
 		this.recordSource(key, locale, true);
 		draft.resolve(id);
+		this.reviewEdited(draft, "apply-suggestion", id);
 	}
 	resolveReview(id) {
 		const draft = this.requireReviews();
@@ -2206,6 +2303,7 @@ var PlanBuilder = class {
 		if (!found) throw errors.X18N5004({ id });
 		this.touched.add(found.key);
 		draft.resolve(id);
+		this.reviewEdited(draft, "resolve-review", id);
 	}
 	markFresh(op) {
 		this.requireReviews();
@@ -2326,6 +2424,14 @@ var PlanBuilder = class {
 				texts.set(target.path, void 0);
 				continue;
 			}
+			if (this.keyFilesLeft.has(s.resource.id) && Object.keys(entry.tree).length === 0) {
+				changes.push({
+					type: "delete",
+					path: target.path
+				});
+				texts.set(target.path, this.state.fileTexts.get(target.path));
+				continue;
+			}
 			const edits = diffText(s.content, this.nextContent(entry, s)).map((e) => ({
 				range: {
 					start: e.range.start + s.offset,
@@ -2357,6 +2463,7 @@ var PlanBuilder = class {
 			});
 			texts.set(path, text);
 		}
+		this.reviewWrites(changes, texts);
 		const review = this.reviewChange();
 		if (review) {
 			changes.push(review);
@@ -2367,6 +2474,41 @@ var PlanBuilder = class {
 			texts
 		};
 	}
+	/** Runs the `reviewEdit` hooks and puts their writes into the changes. */
+	reviewWrites(changes, texts) {
+		const hooks = this.options.registry.plugins.flatMap((plugin) => plugin.reviewEdit ? [plugin.reviewEdit] : []);
+		if (hooks.length === 0 || this.reviewEdits.length === 0) return;
+		const written = /* @__PURE__ */ new Map();
+		const text = (path) => {
+			if (written.has(path)) return written.get(path);
+			const change = changes.find((c) => c.path === path);
+			if (!change) return this.options.text(path);
+			return change.type === "create" ? change.content : change.type === "edit" ? applyTextEdits(texts.get(path) ?? "", change.edits) : void 0;
+		};
+		const ctx = {
+			message: this.options.message,
+			resource: (id) => this.stateById.get(id)?.resource,
+			text
+		};
+		for (const edit of this.reviewEdits) for (const hook of hooks) for (const write of hook(edit, ctx) ?? []) written.set(write.path, write.content);
+		for (const [path, content] of written) {
+			const index = changes.findIndex((c) => c.path === path);
+			const before = index === -1 ? this.options.text(path) : texts.get(path);
+			if (index === -1 && before === content) continue;
+			const change = before === void 0 ? {
+				type: "create",
+				path,
+				content
+			} : {
+				type: "edit",
+				path,
+				edits: diffText(before, content)
+			};
+			if (index === -1) changes.push(change);
+			else changes[index] = change;
+			texts.set(path, before);
+		}
+	}
 	reviewChange() {
 		const reviews = this.state.reviews;
 		if (!reviews || !this.draft?.changed) return void 0;
@@ -2385,6 +2527,7 @@ var PlanBuilder = class {
 };
 function createPlanner(options) {
 	const texts = /* @__PURE__ */ new Map();
+	let textsRevision;
 	/** 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();
@@ -2448,6 +2591,10 @@ function createPlanner(options) {
 	return {
 		plan(ops, answers = {}) {
 			const result = planWith(ops, answers);
+			if (result.plan.revision !== textsRevision) {
+				texts.clear();
+				textsRevision = result.plan.revision;
+			}
 			texts.set(result.plan.id, result.texts);
 			return result.plan;
 		},
@@ -2462,7 +2609,7 @@ function createPlanner(options) {
 			for (const change of fresh.plan.changes) {
 				const current = await options.host.readFile(change.path);
 				const expected = fresh.texts.get(change.path);
-				if (change.type === "edit" && expected !== void 0 && current !== expected || change.type === "create" && current !== void 0) throw errors.X18N4004({ path: change.path });
+				if (change.type !== "create" && expected !== void 0 && current !== expected || change.type === "create" && current !== void 0) throw errors.X18N4004({ path: change.path });
 			}
 			const events = [];
 			for (const change of fresh.plan.changes) events.push(await write(change));
@@ -2871,12 +3018,15 @@ function createProject(options) {
 		const source = message(key, sourceLocale)?.value;
 		return recorded !== void 0 && source !== void 0 && recorded === sourceHash(source);
 	}
-	async function discover() {
-		const ctx = {
+	function finderContext() {
+		return {
 			host,
 			config,
 			extensions: [...new Set(registry.formats.flatMap((format) => format.extensions))]
 		};
+	}
+	async function discover() {
+		const ctx = finderContext();
 		const seen = /* @__PURE__ */ new Map();
 		const out = [];
 		duplicates = [];
@@ -2973,6 +3123,8 @@ function createProject(options) {
 			rawTree: {},
 			ranges: /* @__PURE__ */ new Map(),
 			descriptions: /* @__PURE__ */ new Map(),
+			states: /* @__PURE__ */ new Map(),
+			labels: /* @__PURE__ */ new Map(),
 			error: errors.X18N2001({ path: candidate.path })
 		};
 		try {
@@ -2991,6 +3143,8 @@ function createProject(options) {
 				rawTree: parsed.tree,
 				ranges: parsed.ranges ?? /* @__PURE__ */ new Map(),
 				descriptions,
+				states: parsed.states ?? /* @__PURE__ */ new Map(),
+				labels: parsed.labels ?? /* @__PURE__ */ new Map(),
 				error: void 0
 			};
 		} catch (error) {
@@ -3005,6 +3159,8 @@ function createProject(options) {
 				rawTree: {},
 				ranges: /* @__PURE__ */ new Map(),
 				descriptions: /* @__PURE__ */ new Map(),
+				states: /* @__PURE__ */ new Map(),
+				labels: /* @__PURE__ */ new Map(),
 				error: coded
 			};
 		}
@@ -3022,11 +3178,7 @@ function createProject(options) {
 	}
 	/** A path for a new resource, from the locale finders. */
 	function newResourcePath(locale, namespace, model) {
-		const ctx = {
-			host,
-			config,
-			extensions: [...new Set(registry.formats.flatMap((format) => format.extensions))]
-		};
+		const ctx = finderContext();
 		for (const finder of registry.finders) {
 			const path = finder.resolveNew?.({
 				locale,
@@ -3036,6 +3188,19 @@ function createProject(options) {
 			if (path) return path;
 		}
 	}
+	/** The file of one key, from the locale finders. */
+	function keyFile(key, locale) {
+		const finders = registry.finders.filter((finder) => finder.resolveKey);
+		if (finders.length === 0) return void 0;
+		const ctx = finderContext();
+		for (const finder of finders) {
+			const file = finder.resolveKey?.({
+				key,
+				locale
+			}, ctx);
+			if (file) return file;
+		}
+	}
 	async function loadResources(candidates, reread) {
 		const next = /* @__PURE__ */ new Map();
 		await forEachLimit([...new Set(candidates.map((c) => c.path))], ioConcurrency, async (path) => {
@@ -3165,7 +3330,7 @@ function createProject(options) {
 		usageEligible = (path) => registry.scannersFor(path).length > 0 && include(path) && !exclude(path);
 		await scanPaths((await host.glob(config.usage.include, {
 			ignore: config.usage.exclude,
-			gitignore: true
+			gitignore: config.usage.gitignore
 		})).filter((path) => registry.scannersFor(path).length > 0));
 	}
 	let index;
@@ -3187,7 +3352,8 @@ function createProject(options) {
 					const path = [...stored, segment];
 					const key = keyFor(resource, path);
 					const storedPath = state.toStored(path);
-					const raw = state.ranges.get(pathId(storedPath));
+					const id = pathId(storedPath);
+					const raw = state.ranges.get(id);
 					const range = raw ? {
 						key: shift(raw.key),
 						value: shift(raw.value)
@@ -3204,7 +3370,9 @@ function createProject(options) {
 						messages.set(key, byLocale);
 						const list = byLocale.get(resource.locale) ?? [];
 						byLocale.set(resource.locale, list);
-						const description = state.descriptions.get(pathId(storedPath));
+						const description = state.descriptions.get(id);
+						const translation = state.states.get(id);
+						const label = state.labels.get(id);
 						list.push({
 							key,
 							locale: resource.locale,
@@ -3212,7 +3380,9 @@ function createProject(options) {
 							resource: resource.id,
 							storedPath,
 							range,
-							...description === void 0 ? {} : { description }
+							...description === void 0 ? {} : { description },
+							...translation === void 0 ? {} : { state: translation },
+							...label === void 0 ? {} : { label }
 						});
 						if (!keyPaths.has(key)) keyPaths.set(key, keyIdFor(resource, path));
 					} else {
@@ -3413,6 +3583,7 @@ function createProject(options) {
 			key,
 			namespace: id.namespace,
 			path: id.path,
+			label: list.find((m) => m.label !== void 0)?.label,
 			messages: list,
 			missing: locales.filter((locale) => !byLocale.has(locale) && needs(key, locale)),
 			usages: usageMatches({ key }),
@@ -3565,6 +3736,7 @@ function createProject(options) {
 		basesOf,
 		toStored: (target, path) => storedPathOf(target)(path),
 		resolveNew: newResourcePath,
+		resolveKey: keyFile,
 		update
 	});
 	const ready = (async () => {
@@ -3722,6 +3894,7 @@ function defaultDraft() {
 		usage: {
 			include: ["**/*"],
 			exclude: defaultExclude,
+			gitignore: true,
 			calls: [],
 			regex: [],
 			ignoreCallees: [],
@@ -3748,7 +3921,12 @@ function defaultDraft() {
 	};
 }
 function serializablePart(config) {
-	const { presets, plugins, pluginConfigs, history, ...rest } = config;
+	const { presets, plugins, pluginConfigs, history, ignoreKeys: patterns, ...fields } = config;
+	const ignoreKeys = patterns?.filter((pattern) => !(pattern instanceof RegExp));
+	const rest = ignoreKeys === void 0 ? fields : {
+		...fields,
+		ignoreKeys
+	};
 	if (typeof history !== "object") return {
 		...rest,
 		history
@@ -3823,6 +4001,7 @@ function applyLayer(draft, layer, origin, origins) {
 		draft.usage = {
 			include: usage.include ?? draft.usage.include,
 			exclude: [...draft.usage.exclude, ...usage.exclude ?? []],
+			gitignore: usage.gitignore ?? draft.usage.gitignore,
 			calls: [...draft.usage.calls, ...usage.calls ?? []],
 			regex: [...draft.usage.regex, ...usage.regex ?? []],
 			ignoreCallees: [...draft.usage.ignoreCallees, ...usage.ignoreCallees ?? []],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/core",
   "type": "module",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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

@@ -217,6 +217,9 @@
             "type": "string"
           }
         },
+        "gitignore": {
+          "type": "boolean"
+        },
         "calls": {
           "type": "array",
           "items": {
@@ -632,6 +635,18 @@
               "type": "string"
             }
           },
+          "forms": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
           "note": {
             "type": "string"
           },