@x18n/core 0.1.8 → 0.1.10

package/dist/index.d.mts

@@ -561,6 +561,8 @@ interface CheckContext {
   readonly usages: () => Iterable<Usage>;
   readonly coverage: () => readonly LocaleCoverage[];
   readonly unused: () => readonly KeyString[];
+  /** Fully dynamic usages in a scope (`keyPrefix`, namespace) that may reach the key. `planUnused` keeps a key they reach. */
+  readonly dynamicUsages: (key: KeyString) => readonly Usage[];
   /** Usages whose key is not defined in the source locale. */
   readonly undefinedUsages: () => readonly Usage[];
   readonly placeholders: (value: string) => readonly Placeholder[];
@@ -597,6 +599,20 @@ interface ReportInput {
   readonly diagnostics: readonly Diagnostic[];
   readonly coverage: readonly LocaleCoverage[];
   readonly summary: ReportSummary;
+  /** Set with `x18n check --fix`; `diagnostics` are then the ones left after the fixes (or before them, in a dry run). */
+  readonly fix?: FixSummary | undefined;
+}
+/** What `x18n check --fix` did in a project. */
+interface FixSummary {
+  /** False in a dry run. */
+  readonly applied: boolean;
+  /** Diagnostics whose fix is in the plan. */
+  readonly fixed: number;
+  /** Diagnostics left out because their only bulk fix is `unsafe` (pass `--fix=unsafe`). */
+  readonly skipped: number;
+  /** Files the plan writes, relative to the project root. */
+  readonly files: readonly string[];
+  readonly warnings: readonly string[];
 }
 /** What a check baseline left out (`x18n check --baseline`). */
 interface BaselineSummary {
@@ -650,6 +666,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[];
@@ -688,6 +727,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;
 }
@@ -917,7 +958,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`). */
@@ -940,9 +981,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;
@@ -998,7 +1043,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: {
@@ -1128,11 +1173,13 @@ interface Usage {
   readonly scopePrefix: string | undefined;
 }
 type Severity = "error" | "warning" | "info" | "hint";
+/** A `set` with `replace: false` is skipped, with a warning, when it would replace other keys or a message on its path. */
 type EditOp = {
   readonly type: "set";
   readonly key: KeyString;
   readonly locale: LocaleCode;
   readonly value: MessageLeaf;
+  readonly replace?: boolean;
 } | {
   readonly type: "rename";
   readonly from: KeyString;
@@ -1186,9 +1233,15 @@ interface ExtractItem {
   /** Lines to add once per file when missing, for example an import. */
   readonly imports?: readonly string[];
 }
+/**
+ * How `x18n check --fix` may apply a fix. `safe` fixes only add, so `--fix` applies them; `unsafe` fixes can lose data, so
+ * only `--fix=unsafe` applies them. A fix without a level is offered in the editor and never applied in bulk.
+ */
+type FixLevel = "safe" | "unsafe";
 interface Fix {
   readonly title: string;
   readonly ops: readonly EditOp[];
+  readonly level?: FixLevel | undefined;
 }
 interface Location {
   readonly path: string;
@@ -1283,8 +1336,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
@@ -1627,6 +1683,20 @@ interface UnusedDeletion {
   /** Sorted by key. */
   readonly kept: readonly KeptUnusedKey[];
 }
+/** Which fixes `planFixes` applies. */
+interface FixQuery {
+  /** Also apply `unsafe` fixes (`x18n check --fix=unsafe`). */
+  readonly unsafe?: boolean | undefined;
+}
+/** The fixes of many diagnostics, as one plan: review it (dry run), then pass `plan` to `apply`. */
+interface FixPlan {
+  /** Deletes first, then the other ops, each planned once. */
+  readonly plan: Plan;
+  /** The diagnostics whose fix is in the plan. */
+  readonly fixed: readonly Diagnostic[];
+  /** Diagnostics left out because their only bulk fix is `unsafe` and the query does not allow it. */
+  readonly skipped: readonly Diagnostic[];
+}
 interface ProjectExplanation {
   readonly name: string;
   readonly root: string;
@@ -1772,6 +1842,8 @@ interface Project {
   readonly plan: (ops: readonly EditOp[]) => Plan;
   /** Plans the deletion of the unused keys (`analyze().unused`), minus `ignoreKeys` and keys a scoped fully dynamic usage may reach. */
   readonly planUnused: (query?: UnusedQuery) => UnusedDeletion;
+  /** Plans the first fix of each diagnostic that has a `safe` fix, or also an `unsafe` one with `unsafe: true` (`x18n check --fix`). */
+  readonly planFixes: (diagnostics: readonly Diagnostic[], query?: FixQuery) => FixPlan;
   readonly apply: (plan: Plan, options?: {
     readonly answers?: Answers | undefined;
   }) => Promise<ApplyResult>;
@@ -1908,10 +1980,14 @@ interface LineIndex {
   readonly line: (line: number) => string;
   readonly lineCount: number;
 }
-/** Line index of a text, cached for the few texts used at a time (reporters, LSP ranges). */
+/**
+ * Line index of a text, cached for the few texts used at a time (reporters, LSP ranges).
+ * The least recently used text goes first, so a large resource hit by many diagnostics stays
+ * cached while ranges in many small source files pass through.
+ */
 export declare function createLineIndex(text: string): LineIndex;
 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, KeyFile, KeyId, KeyInfo, 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, 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, FixLevel, FixPlan, FixQuery, FixSummary, 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

@@ -29,14 +29,19 @@ function applyTextEdits(text, edits) {
 	return out;
 }
 const lineIndexes = /* @__PURE__ */ new Map();
-/** Line index of a text, cached for the few texts used at a time (reporters, LSP ranges). */
+/**
+* Line index of a text, cached for the few texts used at a time (reporters, LSP ranges).
+* The least recently used text goes first, so a large resource hit by many diagnostics stays
+* cached while ranges in many small source files pass through.
+*/
 function createLineIndex(text) {
 	let index = lineIndexes.get(text);
-	if (!index) {
+	if (index) lineIndexes.delete(text);
+	else {
 		if (lineIndexes.size >= 16) lineIndexes.delete(lineIndexes.keys().next().value);
 		index = buildLineIndex(text);
-		lineIndexes.set(text, index);
 	}
+	lineIndexes.set(text, index);
 	return index;
 }
 function buildLineIndex(text) {
@@ -379,10 +384,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 +629,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. */
@@ -1112,6 +1124,9 @@ function renderExplanation(e, configFile) {
 	return lines.join("\n");
 }
 //#endregion
+//#region package.json
+var version = "0.1.10";
+//#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. */
@@ -1165,6 +1180,90 @@ function createHistory(input) {
 	};
 }
 //#endregion
+//#region src/project/unused.ts
+/**
+* True when a fully dynamic usage (`t(key)`) may reach `key`: the key lies in the usage's scope namespace and under its
+* scope key prefix. Undefined for a usage without a scope, which may reach any key.
+*/
+function scopeMatcher(usage, namespaced) {
+	const namespace = namespaced ? usage.scopeNamespace : void 0;
+	const prefix = usage.scopePrefix;
+	if (namespace === void 0 && !prefix) return void 0;
+	return (key) => {
+		const id = splitKey(key, namespaced);
+		if (namespace !== void 0 && id.namespace !== namespace) return false;
+		if (!prefix) return true;
+		const path = id.path.join(".");
+		return path === prefix || path.startsWith(`${prefix}.`);
+	};
+}
+function dynamicReach(usages, namespaced) {
+	const scoped = [];
+	const unscoped = [];
+	for (const usage of usages) {
+		if (usage.dynamic !== "unknown") continue;
+		const reaches = scopeMatcher(usage, namespaced);
+		if (reaches) scoped.push({
+			usage,
+			reaches
+		});
+		else unscoped.push(usage);
+	}
+	return {
+		reaching: (key) => scoped.filter((s) => s.reaches(key)).map((s) => s.usage),
+		unscoped
+	};
+}
+/** The plan warning for deleting unused keys while fully dynamic usages without a scope may reach any key. */
+function unscopedWarning(unscoped) {
+	const files = [...new Set(unscoped.map((usage) => usage.path))].sort();
+	const shown = files.length > 5 ? `${files.slice(0, 5).join(", ")} and ${files.length - 5} more files` : files.join(", ");
+	return `${unscoped.length} usage${unscoped.length === 1 ? " has" : "s have"} a fully dynamic key (in ${shown}) that may reach any key; list the keys they use in \`usage.keysInUse\` to keep them.`;
+}
+function planUnusedDeletion(options, query = {}) {
+	const ignored = keyMatcher(options.ignoreKeys);
+	const match = query.glob ? keyMatcher([query.glob]) : void 0;
+	const candidates = [...options.unused].filter((key) => !ignored(key) && (match === void 0 || match(key)) && (query.namespace === void 0 || splitKey(key, options.namespaced).namespace === query.namespace)).sort();
+	const reach = dynamicReach(options.usages, options.namespaced);
+	const keys = [];
+	const kept = [];
+	for (const key of candidates) {
+		const usages = reach.reaching(key);
+		if (usages.length > 0) {
+			kept.push({
+				key,
+				usages
+			});
+			continue;
+		}
+		keys.push({
+			key,
+			messages: options.locations(key).filter((node) => node.leaf).map((node) => ({
+				locale: node.locale,
+				path: node.path
+			}))
+		});
+	}
+	const plan = options.plan(keys.map(({ key }) => ({
+		type: "delete",
+		key,
+		locales: "all"
+	})));
+	if (reach.unscoped.length === 0 || keys.length === 0) return {
+		plan,
+		keys,
+		kept
+	};
+	return {
+		plan: {
+			...plan,
+			warnings: [...plan.warnings, unscopedWarning(reach.unscoped)]
+		},
+		keys,
+		kept
+	};
+}
+//#endregion
 //#region src/project/usages.ts
 function innermost(scopes, range) {
 	let best;
@@ -1503,6 +1602,7 @@ function createAnalyzer(options) {
 			return prefixes.some((prefix) => key.startsWith(prefix));
 		};
 		const unused = hasScanners ? allKeys.filter((key) => !isUsed(key)) : [];
+		const reach = dynamicReach(state.usages, options.namespaced());
 		const undefinedUsages = state.usages.filter((usage) => usage.dynamic === false && usage.key !== void 0 && !isDefined(usage.key));
 		const placeholders = (value) => {
 			let found = placeholderCache.get(value);
@@ -1530,6 +1630,7 @@ function createAnalyzer(options) {
 			usages: () => state.usages,
 			coverage: () => coverage,
 			unused: () => unused,
+			dynamicUsages: reach.reaching,
 			undefinedUsages: () => undefinedUsages,
 			placeholders,
 			placeholderSyntaxes: registry.placeholders,
@@ -1565,6 +1666,55 @@ function createAnalyzer(options) {
 	return { analyze };
 }
 //#endregion
+//#region src/project/fixes.ts
+/** The first fix of a diagnostic that the query allows: `safe`, or also `unsafe` with `unsafe: true`. */
+function pick(diagnostic, unsafe) {
+	return diagnostic.fixes.find((fix) => fix.level === "safe" || unsafe && fix.level === "unsafe");
+}
+/** Identifies ops that do the same: a second `set` of a key in a locale is dropped, so the first value wins. */
+function opId(op) {
+	return op.type === "set" ? JSON.stringify([
+		op.type,
+		op.key,
+		op.locale
+	]) : JSON.stringify(op);
+}
+/**
+* Plans the fixes of many diagnostics as one plan. Deletes go first, so a deleted message makes room for a key that a
+* later `set` with `replace: false` adds under it. Identical ops are planned once.
+*/
+function planFixes(diagnostics, options, query = {}) {
+	const unsafe = query.unsafe === true;
+	const fixed = [];
+	const skipped = [];
+	const deletes = /* @__PURE__ */ new Map();
+	const others = /* @__PURE__ */ new Map();
+	for (const diagnostic of diagnostics) {
+		const fix = pick(diagnostic, unsafe);
+		if (!fix) {
+			if (diagnostic.fixes.some((f) => f.level === "unsafe")) skipped.push(diagnostic);
+			continue;
+		}
+		fixed.push(diagnostic);
+		for (const op of fix.ops) {
+			const ops = op.type === "delete" ? deletes : others;
+			const id = opId(op);
+			if (!ops.has(id)) ops.set(id, op);
+		}
+	}
+	const plan = options.plan([...deletes.values(), ...others.values()]);
+	const deletesEverywhere = [...deletes.values()].some((op) => op.type === "delete" && (op.locales === void 0 || op.locales === "all"));
+	const { unscoped } = dynamicReach(options.usages, options.namespaced);
+	return {
+		plan: deletesEverywhere && unscoped.length > 0 ? {
+			...plan,
+			warnings: [...plan.warnings, unscopedWarning(unscoped)]
+		} : plan,
+		fixed,
+		skipped
+	};
+}
+//#endregion
 //#region src/project/reviews.ts
 const noReviews = {
 	threads: {},
@@ -1736,6 +1886,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);
@@ -1795,6 +1949,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;
@@ -1822,7 +1977,7 @@ var PlanBuilder = class {
 		if (!entry) {
 			entry = {
 				target,
-				tree: target.state?.rawTree ?? {},
+				tree: cloneTree(target.state?.rawTree ?? {}),
 				ops: [],
 				keyRenames: [],
 				formatOnly: false
@@ -1866,7 +2021,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;
@@ -1979,30 +2135,63 @@ 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);
+	/**
+	* Returns the value the set replaced in `before`. Undefined when `replace` is false and the value would replace other keys
+	* or a message on its path: the set is then skipped with a warning.
+	*/
+	setValue(key, locale, value, replace = true) {
 		const existing = this.options.message(key, locale);
 		if (existing) {
-			this.pushOp(this.workFor(this.targetOf(this.writable(existing.resource))), {
+			this.touched.add(key);
+			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);
 		const entry = this.workFor(target);
 		const stored = this.storedPathFor(entry, this.relativePath(key, target));
 		const occupied = nodeAt(entry.tree, stored);
-		if (occupied !== void 0 && !isMessageLeaf(occupied)) this.warnings.push(`"${key}" is a parent of other keys in ${target.path}; they are replaced.`);
+		const parent = occupied !== void 0 && !isMessageLeaf(occupied);
+		if (!replace) {
+			const leaf = stored.slice(0, -1).findIndex((_, i) => {
+				const node = nodeAt(entry.tree, stored.slice(0, i + 1));
+				return node !== void 0 && isMessageLeaf(node);
+			});
+			if (leaf !== -1) {
+				const message = stored.slice(0, leaf + 1).join(keyJoiner(this.separatorOf(target)));
+				this.warnings.push(`"${key}" is not added: "${message}" is a message in ${target.path}, and adding "${key}" would replace it.`);
+				return;
+			}
+			if (parent) {
+				this.warnings.push(`"${key}" is not added: it is a parent of other keys in ${target.path}, and adding it would replace them.`);
+				return;
+			}
+		} else if (parent) this.warnings.push(`"${key}" is a parent of other keys in ${target.path}; they are replaced.`);
+		this.touched.add(key);
 		this.pushOp(entry, {
 			type: "set",
 			path: stored,
 			value
 		});
+		return { before: isMessageLeaf(occupied) ? occupied : void 0 };
 	}
 	deleteMessage(m) {
 		const s = this.writable(m.resource);
@@ -2046,7 +2235,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) => ({
@@ -2061,45 +2250,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);
-			const own = this.options.resolveKey(to, locale);
-			if (!relative || own && own.path !== s.resource.path) {
-				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)?.before;
+		}
+		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) {
@@ -2239,6 +2437,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();
@@ -2249,6 +2458,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();
@@ -2256,6 +2466,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();
@@ -2265,11 +2476,12 @@ var PlanBuilder = class {
 		for (const locale of locales) this.recordSource(op.key, locale, true);
 	}
 	set(op) {
-		this.setValue(op.key, op.locale, op.value);
+		const replace = op.replace !== false;
+		if (!this.setValue(op.key, op.locale, op.value, replace)) return;
 		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, "");
+		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, "", replace);
 	}
 	run(ops) {
 		for (const op of ops) switch (op.type) {
@@ -2415,6 +2627,7 @@ var PlanBuilder = class {
 			});
 			texts.set(path, text);
 		}
+		this.reviewWrites(changes, texts);
 		const review = this.reviewChange();
 		if (review) {
 			changes.push(review);
@@ -2425,6 +2638,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;
@@ -2443,6 +2691,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();
@@ -2506,6 +2755,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;
 		},
@@ -2748,80 +3001,6 @@ function renderPrompt(data) {
 	return out.join("\n");
 }
 //#endregion
-//#region src/project/unused.ts
-/**
-* True when a fully dynamic usage (`t(key)`) may reach `key`: the key lies in the usage's scope namespace and under its
-* scope key prefix. Undefined for a usage without a scope, which may reach any key.
-*/
-function scopeMatcher(usage, namespaced) {
-	const namespace = namespaced ? usage.scopeNamespace : void 0;
-	const prefix = usage.scopePrefix;
-	if (namespace === void 0 && !prefix) return void 0;
-	return (key) => {
-		const id = splitKey(key, namespaced);
-		if (namespace !== void 0 && id.namespace !== namespace) return false;
-		if (!prefix) return true;
-		const path = id.path.join(".");
-		return path === prefix || path.startsWith(`${prefix}.`);
-	};
-}
-function planUnusedDeletion(options, query = {}) {
-	const ignored = keyMatcher(options.ignoreKeys);
-	const match = query.glob ? keyMatcher([query.glob]) : void 0;
-	const candidates = [...options.unused].filter((key) => !ignored(key) && (match === void 0 || match(key)) && (query.namespace === void 0 || splitKey(key, options.namespaced).namespace === query.namespace)).sort();
-	const scoped = [];
-	const unscoped = [];
-	for (const usage of options.usages) {
-		if (usage.dynamic !== "unknown") continue;
-		const reaches = scopeMatcher(usage, options.namespaced);
-		if (reaches) scoped.push({
-			usage,
-			reaches
-		});
-		else unscoped.push(usage);
-	}
-	const keys = [];
-	const kept = [];
-	for (const key of candidates) {
-		const usages = scoped.filter((s) => s.reaches(key)).map((s) => s.usage);
-		if (usages.length > 0) {
-			kept.push({
-				key,
-				usages
-			});
-			continue;
-		}
-		keys.push({
-			key,
-			messages: options.locations(key).filter((node) => node.leaf).map((node) => ({
-				locale: node.locale,
-				path: node.path
-			}))
-		});
-	}
-	const plan = options.plan(keys.map(({ key }) => ({
-		type: "delete",
-		key,
-		locales: "all"
-	})));
-	if (unscoped.length === 0 || keys.length === 0) return {
-		plan,
-		keys,
-		kept
-	};
-	const files = [...new Set(unscoped.map((usage) => usage.path))].sort();
-	const shown = files.length > 5 ? `${files.slice(0, 5).join(", ")} and ${files.length - 5} more files` : files.join(", ");
-	const warning = `${unscoped.length} usage${unscoped.length === 1 ? " has" : "s have"} a fully dynamic key (in ${shown}) that may reach any key; list the keys they use in \`usage.keysInUse\` to keep them.`;
-	return {
-		plan: {
-			...plan,
-			warnings: [...plan.warnings, warning]
-		},
-		keys,
-		kept
-	};
-}
-//#endregion
 //#region src/project/project.ts
 const ioConcurrency = 64;
 async function forEachLimit(items, limit, fn) {
@@ -2861,8 +3040,10 @@ function createProject(options) {
 	const { basesOf, formOf } = derivedKeys(config.usage.derivedKeys);
 	const scanSignature = hashText(JSON.stringify({
 		usage: config.usage,
+		extract: config.extract,
 		namespace: config.namespace,
 		scanners: registry.scanners.map((s) => s.id),
+		version,
 		v: 1
 	}));
 	const localeFilter = (code) => (!config.locales || config.locales.includes(code)) && !config.ignoreLocales.includes(code);
@@ -3440,8 +3621,14 @@ function createProject(options) {
 		basesOf,
 		formOf,
 		localeInfo,
-		text: (path) => fileTexts.get(path) ?? files.get(path)?.text
+		text: (path) => fileTexts.get(path) ?? files.get(path)?.text,
+		namespaced: () => namespaced
 	});
+	let lastAnalysis;
+	function analyze() {
+		if (lastAnalysis?.revision !== revision) lastAnalysis = analyzer.analyze();
+		return lastAnalysis;
+	}
 	function keys(query = {}) {
 		const { messages, keyPaths } = idx();
 		const match = query.glob ? keyMatcher([query.glob], config.keySeparator) : void 0;
@@ -3456,7 +3643,7 @@ function createProject(options) {
 			});
 		}
 		if (query.unused) {
-			const unused = new Set(analyzer.analyze().unused);
+			const unused = new Set(analyze().unused);
 			list = list.filter((key) => unused.has(key));
 		}
 		return list.sort();
@@ -3484,6 +3671,24 @@ function createProject(options) {
 		}
 		return found.sort((a, b) => b.score - a.score || a.value.length - b.value.length || a.key.localeCompare(b.key));
 	}
+	let diagnosticIndex;
+	function diagnosticsOf(key) {
+		const analysis = analyze();
+		if (diagnosticIndex?.analysis !== analysis) {
+			const byKey = /* @__PURE__ */ new Map();
+			for (const d of analysis.diagnostics) {
+				if (d.key === void 0) continue;
+				const list = byKey.get(d.key);
+				if (list) list.push(d);
+				else byKey.set(d.key, [d]);
+			}
+			diagnosticIndex = {
+				analysis,
+				byKey
+			};
+		}
+		return [...diagnosticIndex.byKey.get(key) ?? []];
+	}
 	function get(key) {
 		const { messages, keyPaths } = idx();
 		const byLocale = messages.get(key);
@@ -3498,7 +3703,7 @@ 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: diagnosticsOf(key),
 			reviews: reviews({ key })
 		};
 	}
@@ -3720,7 +3925,7 @@ function createProject(options) {
 			...h,
 			path: p
 		}))),
-		analyze: () => analyzer.analyze(),
+		analyze,
 		async loadHistory(historyOptions = {}) {
 			await ready;
 			await history.load(historyOptions);
@@ -3743,13 +3948,18 @@ function createProject(options) {
 		owns: (path) => fileTexts.has(path) || files.has(path) || usageEligible(path),
 		plan: (ops) => planner.plan(ops),
 		planUnused: (query) => planUnusedDeletion({
-			unused: analyzer.analyze().unused,
+			unused: analyze().unused,
 			usages: idx().usages,
 			namespaced,
 			ignoreKeys: config.ignoreKeys,
 			locations: (key) => project.locations(key),
 			plan: (ops) => planner.plan(ops)
 		}, query),
+		planFixes: (diagnostics, query) => planFixes(diagnostics, {
+			usages: idx().usages,
+			namespaced,
+			plan: (ops) => planner.plan(ops)
+		}, query),
 		apply: (plan, applyOptions) => planner.apply(plan, applyOptions?.answers ?? {}),
 		update,
 		watch() {
@@ -3832,7 +4042,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

package/package.json

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