@x18n/core 0.0.13 → 0.0.14

package/dist/index.d.mts

@@ -434,10 +434,14 @@ interface LocaleFinder {
   readonly id: string;
   readonly override?: boolean | undefined;
   readonly find: (ctx: FinderContext) => Promise<readonly ResourceCandidate[]>;
-  /** Where a new resource for (locale, namespace) should go. Used by edits that create files. */
+  /**
+   * Where a new resource for (locale, namespace) should go. Used by edits that create files.
+   * `model` is the existing resource the new one would otherwise mirror: the key's source file when it has one.
+   */
   readonly resolveNew?: ((target: {
     readonly locale: LocaleCode;
     readonly namespace: string | undefined;
+    readonly model: Resource | undefined;
   }, ctx: FinderContext) => string | undefined) | undefined;
 }
 interface FormatContext {
@@ -459,6 +463,28 @@ type MessageOp = {
   readonly type: "delete";
   readonly path: readonly string[];
 };
+/** A built-in format known by its extensions only: the module behind `load` is imported when a file of that format is read. */
+interface FormatEntry {
+  /** File extensions without the dot. */
+  readonly extensions: readonly string[];
+  /** The module's default export creates a plugin that holds the format. */
+  readonly load: PluginLoader;
+}
+/** A format entry under its id, as plugins list it. */
+interface LazyFormat extends FormatEntry {
+  readonly id: string;
+}
+/** A built-in scanner known by its extensions only: the module behind `load` is imported when a file it scans is first scanned. */
+interface ScannerEntry {
+  /** File extensions without dot. `*` matches every file. */
+  readonly extensions: readonly string[];
+  /** The module's default export creates a plugin that holds the scanner. */
+  readonly load: PluginLoader;
+}
+/** A scanner entry under its id, as plugins list it. */
+interface LazyScanner extends ScannerEntry {
+  readonly id: string;
+}
 interface Format {
   readonly id: string;
   /** File extensions without the dot. */
@@ -496,6 +522,8 @@ interface Scope {
   readonly range: TextRange;
   readonly namespace?: string | undefined;
   readonly keyPrefix?: string | undefined;
+  /** The key prefix applies only to keys it defines; others resolve without it, as page messages that extend global ones. */
+  readonly optionalPrefix?: boolean | undefined;
 }
 interface HardString {
   readonly text: string;
@@ -703,6 +731,10 @@ interface Plugin {
   readonly manifests?: readonly ManifestReader[] | undefined;
   readonly localeFinders?: readonly LocaleFinder[] | undefined;
   readonly formats?: readonly Format[] | undefined;
+  /** Formats that load their module when a file of that format is first read. */
+  readonly lazyFormats?: readonly LazyFormat[] | undefined;
+  /** Scanners that load their module when a file they scan is first scanned. */
+  readonly lazyScanners?: readonly LazyScanner[] | undefined;
   readonly scanners?: readonly Scanner[] | undefined;
   readonly extractors?: readonly Extractor[] | undefined;
   readonly checks?: readonly Check[] | undefined;
@@ -727,6 +759,32 @@ interface Preset {
 }
 /** A preset factory as referenced by name from YAML and JSON configs. */
 type PresetFactory = (options?: JsonObject) => Preset;
+/** Loads a plugin on demand, usually `() => import('./plugin')`: the module's default export creates it. */
+type PluginLoader = () => Promise<{
+  readonly default: () => Plugin;
+}>;
+/** Loads a reporter on demand, usually `() => import('./reporter')`: the module's default export is the reporter. */
+type ReporterLoader = () => Promise<{
+  readonly default: Reporter;
+}>;
+/** Loads a preset on demand, usually `() => import('./preset')`: the module's default export is the factory. */
+type PresetLoader = () => Promise<{
+  readonly default: PresetFactory;
+}>;
+/** When a built-in preset applies. Cheap, so it stays loaded while the preset module does not. */
+interface PresetDetection {
+  /** Without `detect`, the preset applies only when listed in config. */
+  readonly detect?: ((ctx: DetectContext) => boolean | Promise<boolean>) | undefined;
+  /** When true and detected, presets that come after it are not applied. */
+  readonly exclusive?: boolean | undefined;
+}
+/**
+ * A built-in preset split in two: the detection is always loaded; the module behind `load`
+ * is imported only when it passes or the preset is listed in config.
+ */
+interface PresetEntry extends PresetDetection {
+  readonly load: PresetLoader;
+}
 //#endregion
 //#region src/types/config.d.ts
 /** Where a value comes from: an argument, or a property of an object argument. */
@@ -742,8 +800,8 @@ interface CallSpec {
   readonly kind?: "call" | "selector" | "accessor" | undefined;
   /** Which argument holds the key. Default 0. */
   readonly key?: number | ArgSource | undefined;
-  /** Where the namespace comes from (call option, or factory argument when `factory` is true). */
-  readonly namespace?: ArgSource | undefined;
+  /** Where the namespace comes from (call option, or factory argument when `factory` is true), or a fixed namespace such as `'shared'` for a hook that wraps `useTranslation('shared')`. */
+  readonly namespace?: ArgSource | string | undefined;
   /** Where a key prefix comes from (`keyPrefix` option, or next-intl `useTranslations('a.b')`). */
   readonly keyPrefix?: ArgSource | undefined;
   /** The callee is a factory that returns the translate function, for example `useI18n()` returning `{ t }`. */
@@ -835,6 +893,12 @@ interface NamespaceOptions {
   readonly separator?: string | undefined;
   /** Namespace of keys written without one. */
   readonly default?: string | undefined;
+  /** Namespaces searched in order when a key written without a namespace is not in its own (i18next `fallbackNS`). */
+  readonly fallback?: readonly string[] | undefined;
+  /** Namespace of keys written without one, per glob of source files, before `default`: `{ 'packages/admin/**': 'admin' }`. */
+  readonly byFile?: {
+    readonly [glob: string]: string;
+  } | undefined;
   /** 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;
 }
@@ -926,6 +990,10 @@ interface ResolvedConfig {
   readonly namespace: {
     readonly separator: string;
     readonly default: string | undefined;
+    readonly fallback: readonly string[];
+    readonly byFile: {
+      readonly [glob: string]: string;
+    };
     readonly fromPath: NamespaceFromPath;
   };
   readonly usage: {
@@ -984,6 +1052,34 @@ export declare function keyMatcher(globs: readonly string[]): (key: KeyString) =
 /** Matcher over posix file paths. */
 export declare function pathMatcher(globs: readonly string[]): (path: string) => boolean;
 //#endregion
+//#region src/library.d.ts
+interface LibraryOptions {
+  /** The plugin name, prefixed by the caller: `x18n:vue-i18n`. */
+  readonly name: string;
+  readonly calls?: readonly CallSpec[];
+  /** i18n-ally style `usageMatchRegex` patterns, for languages without an AST scanner. */
+  readonly regex?: readonly RegexScannerSpec[];
+  /** The library's placeholder syntaxes. */
+  readonly placeholders?: readonly PlaceholderSyntax[];
+  readonly derivedKeys?: readonly string[];
+  readonly namespace?: {
+    readonly separator?: string;
+    readonly default?: string;
+    readonly fromPath?: NamespaceFromPath;
+  };
+  /** Default resource patterns (i18n-ally `preferredLocalePaths` + `pathMatcher`). */
+  readonly resources?: readonly ResourceSpec[];
+  readonly keyStyle?: "nested" | "flat";
+  readonly templates?: readonly ExtractTemplate[];
+  readonly finders?: readonly LocaleFinder[];
+  readonly normalizeKey?: Plugin["normalizeKey"];
+  readonly transformResource?: ResourceTransform;
+  readonly extra?: (draft: ConfigDraft, ctx: ConfigContext) => void | Promise<void>;
+  readonly translatePrompt?: Plugin["translatePrompt"];
+}
+/** One plugin holding a library's call specs, regexes, namespace rules, defaults and extraction templates. */
+export declare function createLibraryPlugin(options: LibraryOptions): Plugin;
+//#endregion
 //#region src/locale.d.ts
 /** Lenient display parse of a locale code (`zh_CN`, `pt-BR`, `sr-Latn-RS`). Never changes the code. */
 export declare function parseLocaleInfo(code: LocaleCode): LocaleInfo;
@@ -1036,9 +1132,11 @@ interface CapabilityConflict {
 /** The capabilities of the final plugin list, indexed for the project engine. */
 interface PluginRegistry {
   readonly plugins: readonly Plugin[];
-  readonly formats: readonly Format[];
+  /** Every format, loaded or not; use `formatFor` and `loadFormatFor` to run one. */
+  readonly formats: readonly (Format | LazyFormat)[];
   readonly finders: readonly LocaleFinder[];
-  readonly scanners: readonly Scanner[];
+  /** Every scanner, loaded or not. */
+  readonly scanners: readonly (Scanner | LazyScanner)[];
   readonly checks: ReadonlyMap<string, Check>;
   readonly reporters: ReadonlyMap<string, Reporter>;
   readonly placeholders: readonly PlaceholderSyntax[];
@@ -1046,10 +1144,18 @@ interface PluginRegistry {
   readonly extractors: readonly Extractor[];
   readonly histories: readonly HistoryProvider[];
   readonly conflicts: readonly CapabilityConflict[];
-  /** Format for a file path: config `formats` first, then the first format that claims the extension. */
+  /** 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;
+  /** The id of the format `formatFor` would pick, loaded or not. */
+  readonly formatIdFor: (path: string, hint?: string) => string | undefined;
+  /** The loaded format with this id. */
   readonly formatById: (id: string) => Format | undefined;
-  readonly scannersFor: (path: string) => readonly Scanner[];
+  /** Loads the format of a file path, once, and returns it. */
+  readonly loadFormatFor: (path: string, hint?: string) => Promise<Format | undefined>;
+  /** The scanners that handle a file path, loaded or not. */
+  readonly scannersFor: (path: string) => readonly (Scanner | LazyScanner)[];
+  /** Loads the scanners of a file path, once each, and returns them. */
+  readonly loadScannersFor: (path: string) => Promise<readonly Scanner[]>;
 }
 export declare function extensionOf(path: string): string;
 export declare function createRegistry(input: readonly Plugin[], config: Pick<ResolvedConfig, "formats">): PluginRegistry;
@@ -1116,7 +1222,7 @@ export declare function renderPrompt(data: PromptData): string;
 interface Builtins {
   readonly plugins: readonly Plugin[];
   readonly presets: {
-    readonly [name: string]: PresetFactory;
+    readonly [name: string]: PresetEntry;
   };
 }
 interface ResolveConfigOptions {
@@ -1473,4 +1579,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, GlobOptions, GlossaryEntry, HardString, HistoryConfigs, HistoryContext, HistoryOptions, HistoryProvider, HistorySettings, Host, JsonObject, JsonPrimitive, JsonValue, KeyContext, KeyId, KeyInfo, KeyQuery, KeyString, KeyTarget, 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, PluginOption, PluginRegistry, PluginSpecifier, PluralForm, Preset, PresetExplanation, PresetFactory, PresetOption, Project, ProjectChange, ProjectExplanation, PromptContext, PromptData, PromptDraft, PromptItem, PromptOptions, RegexScannerSpec, ReportInput, ReportSummary, Reporter, ReporterContext, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ScanContext, ScanResult, Scanner, 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, 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 };

package/dist/index.mjs

@@ -138,7 +138,9 @@ function defineConfig(config) {
 }
 //#endregion
 //#region src/errors.ts
-const at = (p) => p.line === void 0 ? p.path : `${p.path}:${p.line}`;
+function at(p) {
+	return p.line === void 0 ? p.path : `${p.path}:${p.line}`;
+}
 /**
 * Every coded error. Groups: 0xxx config, 1xxx plugin, 2xxx discovery and parse,
 * 3xxx scanning, 4xxx edits, 5xxx reviews. `fix` stays static so the docs can show it.
@@ -331,6 +333,40 @@ function pathMatcher(globs) {
 	return (path) => regexes.some((re) => re.test(path));
 }
 //#endregion
+//#region src/library.ts
+/** One plugin holding a library's call specs, regexes, namespace rules, defaults and extraction templates. */
+function createLibraryPlugin(options) {
+	return {
+		name: options.name,
+		async config(draft, ctx) {
+			if (options.namespace) draft.namespace = {
+				...draft.namespace,
+				separator: options.namespace.separator ?? draft.namespace.separator,
+				default: draft.namespace.default ?? options.namespace.default,
+				fromPath: options.namespace.fromPath ?? draft.namespace.fromPath
+			};
+			if (options.resources) draft.resources = [...draft.resources, ...options.resources.filter((spec) => !draft.resources.some((r) => r.pattern === spec.pattern))];
+			if (options.keyStyle && draft.keyStyle === "auto" && !ctx.user.keyStyle) draft.keyStyle = options.keyStyle;
+			draft.usage = {
+				...draft.usage,
+				calls: [...draft.usage.calls, ...options.calls ?? []],
+				regex: [...draft.usage.regex, ...options.regex ?? []],
+				derivedKeys: [...draft.usage.derivedKeys, ...options.derivedKeys ?? []]
+			};
+			await options.extra?.(draft, ctx);
+		},
+		placeholders: options.placeholders,
+		localeFinders: options.finders,
+		normalizeKey: options.normalizeKey,
+		transformResource: options.transformResource,
+		translatePrompt: options.translatePrompt,
+		extractors: options.templates ? [{
+			id: options.name,
+			templates: options.templates
+		}] : void 0
+	};
+}
+//#endregion
 //#region src/locale.ts
 const defaultRegions = {
 	ar: "SA",
@@ -585,8 +621,8 @@ function uniqueById(items, kind) {
 }
 function createRegistry(input, config) {
 	const plugins = sortByEnforce(input);
-	const formats = plugins.flatMap((plugin) => plugin.formats ?? []);
-	const scanners = plugins.flatMap((plugin) => plugin.scanners ?? []);
+	const formats = plugins.flatMap((plugin) => [...plugin.formats ?? [], ...plugin.lazyFormats ?? []]);
+	const scanners = plugins.flatMap((plugin) => [...plugin.scanners ?? [], ...plugin.lazyScanners ?? []]);
 	const finders = [...uniqueById(plugins.flatMap((plugin) => plugin.localeFinders ?? []), "Locale finder").values()];
 	const checks = uniqueById(plugins.flatMap((plugin) => plugin.checks ?? []), "Check");
 	const reporters = uniqueById(plugins.flatMap((plugin) => plugin.reporters ?? []), "Reporter");
@@ -602,8 +638,58 @@ function createRegistry(input, config) {
 		});
 		else byExtension.set(extension, format);
 	}
-	const formatById = (id) => formats.find((format) => format.id === id);
+	const isLazy = (format) => "load" in format;
+	const loaded = new Map(formats.filter((format) => !isLazy(format)).map((format) => [format.id, format]));
+	const loading = /* @__PURE__ */ new Map();
+	const formatById = (id) => loaded.get(id);
+	const formatIdFor = (path, hint) => {
+		if (hint) return hint;
+		const extension = extensionOf(path);
+		return config.formats[extension] ?? byExtension.get(extension)?.id;
+	};
+	const loadFormat = (id) => {
+		const ready = loaded.get(id);
+		if (ready) return Promise.resolve(ready);
+		const lazy = formats.find((format) => format.id === id);
+		if (!lazy || !isLazy(lazy)) return Promise.resolve(void 0);
+		let pending = loading.get(id);
+		if (!pending) {
+			pending = lazy.load().then((mod) => {
+				const format = mod.default().formats?.find((item) => item.id === id && !isLazy(item));
+				if (format) loaded.set(id, format);
+				return format;
+			});
+			loading.set(id, pending);
+		}
+		return pending;
+	};
 	const scannerCache = /* @__PURE__ */ new Map();
+	const loadedScanners = new Map(scanners.filter((scanner) => !("load" in scanner)).map((scanner) => [scanner.id, scanner]));
+	const loadingScanners = /* @__PURE__ */ new Map();
+	const loadScanner = (entry) => {
+		if (!("load" in entry)) return Promise.resolve(entry);
+		const ready = loadedScanners.get(entry.id);
+		if (ready) return Promise.resolve(ready);
+		let pending = loadingScanners.get(entry.id);
+		if (!pending) {
+			pending = entry.load().then((mod) => {
+				const scanner = mod.default().scanners?.find((item) => item.id === entry.id);
+				if (scanner) loadedScanners.set(entry.id, scanner);
+				return scanner;
+			});
+			loadingScanners.set(entry.id, pending);
+		}
+		return pending;
+	};
+	const scannersFor = (path) => {
+		const extension = extensionOf(path);
+		let list = scannerCache.get(extension);
+		if (!list) {
+			list = extension ? scanners.filter((scanner) => scanner.extensions.includes(extension) || scanner.extensions.includes("*")) : [];
+			scannerCache.set(extension, list);
+		}
+		return list;
+	};
 	return {
 		plugins,
 		formats,
@@ -617,20 +703,18 @@ function createRegistry(input, config) {
 		histories: plugins.flatMap((plugin) => plugin.histories ?? []),
 		conflicts,
 		formatById,
+		formatIdFor,
 		formatFor(path, hint) {
-			if (hint) return formatById(hint);
-			const extension = extensionOf(path);
-			const mapped = config.formats[extension];
-			return mapped ? formatById(mapped) : byExtension.get(extension);
+			const id = formatIdFor(path, hint);
+			return id === void 0 ? void 0 : formatById(id);
 		},
-		scannersFor(path) {
-			const extension = extensionOf(path);
-			let list = scannerCache.get(extension);
-			if (!list) {
-				list = extension ? scanners.filter((scanner) => scanner.extensions.includes(extension) || scanner.extensions.includes("*")) : [];
-				scannerCache.set(extension, list);
-			}
-			return list;
+		async loadFormatFor(path, hint) {
+			const id = formatIdFor(path, hint);
+			return id === void 0 ? void 0 : loadFormat(id);
+		},
+		scannersFor,
+		async loadScannersFor(path) {
+			return (await Promise.all(scannersFor(path).map(loadScanner))).filter((scanner) => scanner !== void 0);
 		}
 	};
 }
@@ -665,7 +749,7 @@ const callSpec = v.strictObject({
 		"accessor"
 	])),
 	key: v.optional(v.union([v.number(), argSource])),
-	namespace: v.optional(argSource),
+	namespace: v.optional(v.union([argSource, v.string()])),
 	keyPrefix: v.optional(argSource),
 	factory: v.optional(v.boolean()),
 	returns: v.optional(strings),
@@ -724,6 +808,8 @@ const checkSetting = v.union([level, v.tuple([level, jsonObject])]);
 const namespaceOptions = v.strictObject({
 	separator: v.optional(v.string()),
 	default: v.optional(v.string()),
+	fallback: v.optional(strings),
+	byFile: v.optional(v.record(v.string(), v.string())),
 	fromPath: v.optional(v.picklist([
 		"dot",
 		"slash",
@@ -949,8 +1035,12 @@ function innermost(scopes, range) {
 	return best;
 }
 function createUsageResolver(config, namespaced, normalizers) {
-	const separator = config.namespace.separator;
-	return { resolve(candidate, scopes, path, scanner) {
+	const { separator, fallback } = config.namespace;
+	const byFile = Object.entries(config.namespace.byFile).map(([glob, namespace]) => ({
+		matches: pathMatcher([glob]),
+		namespace
+	}));
+	return { resolve(candidate, scopes, path, scanner, has) {
 		const scope = innermost(scopes, candidate.range);
 		const ctx = { path };
 		let text = candidate.raw;
@@ -961,8 +1051,8 @@ function createUsageResolver(config, namespaced, normalizers) {
 				break;
 			}
 		}
-		const scopeNamespace = candidate.namespace ?? scope?.namespace;
-		const scopePrefix = candidate.keyPrefix ?? scope?.keyPrefix;
+		const scopeNamespace = candidate.namespace ?? scope?.namespace ?? byFile.find((rule) => rule.matches(path))?.namespace;
+		let scopePrefix = candidate.keyPrefix ?? scope?.keyPrefix;
 		let namespace;
 		let explicit = false;
 		if (namespaced) {
@@ -973,10 +1063,17 @@ function createUsageResolver(config, namespaced, normalizers) {
 				text = text.slice(index + separator.length);
 			} else namespace = scopeNamespace ?? config.namespace.default;
 		}
-		if (scopePrefix && !explicit) text = text ? `${scopePrefix}.${text}` : scopePrefix;
+		if (scopePrefix && !explicit) {
+			const prefixed = text ? `${scopePrefix}.${text}` : scopePrefix;
+			const lookup = candidate.dynamic === "prefix" ? prefixed.replace(/\.$/, "") : prefixed;
+			if (candidate.keyPrefix || !scope?.optionalPrefix || has(joinKey(namespace, lookup.split(".")))) text = prefixed;
+			else scopePrefix = void 0;
+		}
+		const keyPath = text === "" ? [] : text.split(".");
 		let key;
 		if (candidate.dynamic === "unknown") key = void 0;
-		else key = joinKey(namespace, text === "" ? [] : text.split("."));
+		else key = joinKey(namespace, keyPath);
+		if (key !== void 0 && namespaced && !explicit && candidate.dynamic === false && !has(key)) key = fallback.map((ns) => joinKey(ns, keyPath)).find(has) ?? key;
 		return {
 			key,
 			raw: candidate.raw,
@@ -1345,7 +1442,8 @@ function mirrorPath(path, from, to) {
 function importEdit(text, lines) {
 	const missing = lines.filter((line) => !text.includes(line.trim()));
 	if (missing.length === 0) return void 0;
-	const script = /<script\b[^>]*>\r?\n?/.exec(text);
+	const open = /^\s*---\r?\n/.exec(text);
+	const script = (open && /^---\s*$/m.test(text.slice(open[0].length)) ? open : void 0) ?? /<script\b[^>]*>\r?\n?/.exec(text);
 	let at = 0;
 	if (script) at = script.index + script[0].length;
 	else {
@@ -1439,7 +1537,9 @@ var PlanBuilder = class {
 		const sourceState = source && this.stateById.get(source.resource);
 		const namespace = namespaced ? this.keyId(key).namespace ?? this.config.namespace.default : sourceState?.resource.namespace;
 		const exists = (path) => resources.some((r) => r.resource.path === path);
-		const resolved = this.options.resolveNew(locale, namespace);
+		const sibling = (r) => r.resource.locale === locale && r.resource.namespace !== void 0 && namespace !== void 0;
+		const model = (sourceState && fits(sourceState) ? sourceState : void 0) ?? resources.find((s) => s.resource.locale === sourceLocale && fits(s)) ?? resources.find(fits) ?? resources.find(sibling);
+		const resolved = this.options.resolveNew(locale, namespace, model?.resource);
 		if (resolved && !exists(resolved)) {
 			const format = this.options.registry.formatFor(resolved);
 			if (format?.serialize) {
@@ -1455,8 +1555,6 @@ var PlanBuilder = class {
 				return target;
 			}
 		}
-		const sibling = (r) => r.resource.locale === locale && r.resource.namespace !== void 0 && namespace !== void 0;
-		const model = (sourceState && fits(sourceState) ? sourceState : void 0) ?? resources.find((s) => s.resource.locale === sourceLocale && fits(s)) ?? resources.find(fits) ?? resources.find(sibling);
 		const format = model && this.options.registry.formatById(model.resource.format);
 		let path = model && mirrorPath(model.resource.path, model.resource.locale, locale);
 		if (model && path && namespace !== void 0 && model.resource.namespace !== void 0 && model.resource.namespace !== namespace) path = mirrorPath(path, model.resource.namespace, namespace);
@@ -2265,6 +2363,22 @@ function createProject(options) {
 		if (state.error) return void 0;
 		return new Map([...walkLeaves(state.tree)].map((leaf) => [keyFor(state.resource, leaf.path), leaf.value]));
 	}
+	/** 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))]
+		};
+		for (const finder of registry.finders) {
+			const path = finder.resolveNew?.({
+				locale,
+				namespace,
+				model
+			}, ctx);
+			if (path) return path;
+		}
+	}
 	async function loadResources(candidates, reread) {
 		const next = /* @__PURE__ */ new Map();
 		const paths = [...new Set(candidates.map((c) => c.path))];
@@ -2276,6 +2390,7 @@ function createProject(options) {
 			}
 		}));
 		namespaced = config.namespace.separator !== "." && candidates.some((c) => c.namespace !== void 0);
+		await Promise.all(candidates.map((candidate) => registry.loadFormatFor(candidate.path, candidate.format)));
 		for (const candidate of candidates) {
 			const text = fileTexts.get(candidate.path);
 			if (text === void 0) continue;
@@ -2296,6 +2411,11 @@ function createProject(options) {
 		resolver = createUsageResolver(config, namespaced, normalizers);
 		resolved = /* @__PURE__ */ new WeakMap();
 		resourceIndex = void 0;
+		const namespaces = /* @__PURE__ */ new Set([void 0, ...[...resourceStates.values()].map((state) => state.resource.namespace)]);
+		await Promise.all([...namespaces].map((namespace) => {
+			const path = newResourcePath(sourceLocale, namespace, void 0);
+			return path ? registry.loadFormatFor(path) : void 0;
+		}));
 	}
 	async function scanOne(file) {
 		const usages = [];
@@ -2303,7 +2423,7 @@ function createProject(options) {
 		const keySlots = [];
 		const hardStrings = [];
 		const calls = config.usage.calls.filter((spec) => ![spec.callee].flat().some((name) => config.usage.ignoreCallees.includes(name)));
-		for (const scanner of registry.scannersFor(file.path)) {
+		for (const scanner of await registry.loadScannersFor(file.path)) {
 			const result = await scanner.scan(file, {
 				config,
 				calls
@@ -2470,12 +2590,13 @@ function createProject(options) {
 		};
 	}
 	function buildIndex() {
-		resourceIndex ??= buildResourceIndex();
+		const { messages, parents, derived } = resourceIndex ??= buildResourceIndex();
+		const has = (key) => messages.has(key) || parents.has(key) || derived.has(key);
 		const usages = [];
 		for (const [path, state] of [...files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
 			let list = resolved.get(state);
 			if (!list) {
-				list = state.result.usages.map((candidate) => resolver.resolve(candidate, state.result.scopes ?? [], path, "scanner"));
+				list = state.result.usages.map((candidate) => resolver.resolve(candidate, state.result.scopes ?? [], path, "scanner", has));
 				resolved.set(state, list);
 			}
 			usages.push(...list);
@@ -2708,8 +2829,9 @@ function createProject(options) {
 			const before = idx();
 			const paths = new Set(events.map((event) => event.path));
 			const resourcePaths = new Set([...resourceStates.values()].map((state) => state.resource.path));
-			const maybeResource = (path) => !resourcePaths.has(path) && registry.formatFor(path) !== void 0 && !usageEligible(path);
-			const structural = events.some((event) => event.type !== "change" || maybeResource(event.path));
+			const maybeResource = (path) => !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) => ({
 				...state.resource,
 				format: state.resource.format === "unknown" ? void 0 : state.resource.format
@@ -2750,20 +2872,7 @@ function createProject(options) {
 		text: (path) => fileTexts.get(path) ?? files.get(path)?.text,
 		basesOf,
 		toStored: (target, path) => storedPathOf(target)(path),
-		resolveNew(locale, namespace) {
-			const ctx = {
-				host,
-				config,
-				extensions: [...new Set(registry.formats.flatMap((format) => format.extensions))]
-			};
-			for (const finder of registry.finders) {
-				const path = finder.resolveNew?.({
-					locale,
-					namespace
-				}, ctx);
-				if (path) return path;
-			}
-		},
+		resolveNew: newResourcePath,
 		update
 	});
 	const ready = (async () => {
@@ -2894,6 +3003,8 @@ function defaultDraft() {
 		namespace: {
 			separator: ".",
 			default: void 0,
+			fallback: [],
+			byFile: {},
 			fromPath: "dot"
 		},
 		usage: {
@@ -2977,6 +3088,11 @@ function applyLayer(draft, layer, origin, origins) {
 		draft.namespace = {
 			separator: layer.namespace.separator ?? draft.namespace.separator,
 			default: layer.namespace.default ?? draft.namespace.default,
+			fallback: layer.namespace.fallback ?? draft.namespace.fallback,
+			byFile: {
+				...draft.namespace.byFile,
+				...layer.namespace.byFile
+			},
 			fromPath: layer.namespace.fromPath ?? draft.namespace.fromPath
 		};
 		mark("namespace");
@@ -3081,8 +3197,8 @@ function createLoader(options) {
 		if (option === false || option === void 0) return void 0;
 		if (typeof option === "object" && !Array.isArray(option)) return option;
 		const [specifier, pluginOptions] = typeof option === "string" ? [option, void 0] : [option[0], option[1]];
-		const factory = options.builtins.presets[specifier];
-		if (factory) return factory(pluginOptions);
+		const entry = options.builtins.presets[specifier];
+		if (entry) return (await entry.load()).default(pluginOptions);
 		if (!options.loadPlugin) throw errors.X18N1003({ preset: specifier });
 		return options.loadPlugin(specifier, pluginOptions);
 	};
@@ -3118,7 +3234,17 @@ async function expandPresets(presets, userPlugins, listed, detectCtx) {
 		name: preset.name,
 		reason: "after-exclusive"
 	});
-	else stopped = await flatten(preset, listed);
+	else if ("entry" in preset) {
+		const applies = listed || (preset.entry.detect ? await preset.entry.detect(detectCtx) : false);
+		explanations.push({
+			name: preset.name,
+			reason: applies ? listed ? "listed" : "detected" : "not-detected"
+		});
+		if (!applies) continue;
+		const loaded = (await preset.entry.load()).default();
+		for (const child of loaded.plugins) await flatten(child, false);
+		stopped = preset.entry.exclusive === true || loaded.exclusive === true;
+	} else stopped = await flatten(preset, listed);
 	for (const plugin of userPlugins) await flatten(plugin, true);
 	return {
 		plugins,
@@ -3141,7 +3267,10 @@ async function resolveConfig(options) {
 	const userPlugins = await loadAll(load, [...options.parent?.plugins ?? [], ...user.plugins ?? []]);
 	const presetOption = user.presets ?? options.parent?.presets ?? "auto";
 	const auto = presetOption === "auto";
-	const presets = auto ? Object.values(builtins.presets).map((factory) => factory()) : (await loadAll(load, presetOption)).map((item) => isPreset(item) ? item : {
+	const presets = auto ? Object.entries(builtins.presets).map(([name, entry]) => ({
+		name,
+		entry
+	})) : (await loadAll(load, presetOption)).map((item) => isPreset(item) ? item : {
 		name: item.name,
 		plugins: [item]
 	});
@@ -3182,4 +3311,4 @@ async function resolveConfig(options) {
 	};
 }
 //#endregion
-export { ConfigSchema, PluginFileSchema, applyMessageOps, applyTextEdits, buildTree, contractVersion, 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, 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 };

package/package.json

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

@@ -145,6 +145,21 @@
         "default": {
           "type": "string"
         },
+        "fallback": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "byFile": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
         "fromPath": {
           "enum": [
             "dot",
@@ -221,19 +236,26 @@
                 ]
               },
               "namespace": {
-                "type": "object",
-                "properties": {
-                  "arg": {
-                    "type": "number"
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "arg": {
+                        "type": "number"
+                      },
+                      "property": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "arg"
+                    ],
+                    "additionalProperties": false
                   },
-                  "property": {
+                  {
                     "type": "string"
                   }
-                },
-                "required": [
-                  "arg"
-                ],
-                "additionalProperties": false
+                ]
               },
               "keyPrefix": {
                 "type": "object",

package/schema/plugin.json

@@ -90,6 +90,21 @@
             "default": {
               "type": "string"
             },
+            "fallback": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "byFile": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
             "fromPath": {
               "enum": [
                 "dot",
@@ -166,19 +181,26 @@
                 ]
               },
               "namespace": {
-                "type": "object",
-                "properties": {
-                  "arg": {
-                    "type": "number"
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "arg": {
+                        "type": "number"
+                      },
+                      "property": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "arg"
+                    ],
+                    "additionalProperties": false
                   },
-                  "property": {
+                  {
                     "type": "string"
                   }
-                },
-                "required": [
-                  "arg"
-                ],
-                "additionalProperties": false
+                ]
               },
               "keyPrefix": {
                 "type": "object",