@saykit/config 0.6.1 → 0.8.0

package/dist/commands/index.cjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 const require_storage = require("../storage-DqhzA5H8.cjs");
-const require_loader = require("../loader-A1uS7qkK.cjs");
+const require_loader = require("../loader-BdCeoj3-.cjs");
 let _commander_js_extra_typings = require("@commander-js/extra-typings");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");

package/dist/commands/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { a as mergeExtractedMessages, i as expandBucketOutputPath, n as writeCatalogueMessages, o as pruneLocaleMessages, t as readCatalogueMessages } from "../storage-B6mn0s3V.mjs";
-import { t as resolveConfig } from "../loader-DLyuZzF2.mjs";
+import { t as resolveConfig } from "../loader-DwF1lM3f.mjs";
 import { Command, program } from "@commander-js/extra-typings";
 import { access, glob, readFile, stat, watch } from "node:fs/promises";
 import { join, relative } from "node:path";

package/dist/features/loader/index.cjs

@@ -1,3 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_loader = require("../../loader-A1uS7qkK.cjs");
+const require_loader = require("../../loader-BdCeoj3-.cjs");
 exports.resolveConfig = require_loader.resolveConfig;
+exports.resolveConfigFile = require_loader.resolveConfigFile;

package/dist/features/loader/index.d.cts

@@ -1,5 +1,11 @@
 import { n as Config } from "../../shapes-CRlXtss0.cjs";
 //#region src/features/loader/resolve.d.ts
+/**
+ * The config file {@link resolveConfig} would load, for callers that need the
+ * path itself rather than its contents — salting a bundler's cache key with it,
+ * for one, since what a catalogue assembles into depends on the config.
+ */
+declare function resolveConfigFile(name?: string): string;
 declare function resolveConfig(name?: string): Config;
 //#endregion
-export { resolveConfig };
+export { resolveConfig, resolveConfigFile };

package/dist/features/loader/index.d.mts

@@ -1,5 +1,11 @@
 import { n as Config } from "../../shapes-CRlXtss0.mjs";
 //#region src/features/loader/resolve.d.ts
+/**
+ * The config file {@link resolveConfig} would load, for callers that need the
+ * path itself rather than its contents — salting a bundler's cache key with it,
+ * for one, since what a catalogue assembles into depends on the config.
+ */
+declare function resolveConfigFile(name?: string): string;
 declare function resolveConfig(name?: string): Config;
 //#endregion
-export { resolveConfig };
+export { resolveConfig, resolveConfigFile };

package/dist/features/loader/index.mjs

@@ -1,2 +1,2 @@
-import { t as resolveConfig } from "../../loader-DLyuZzF2.mjs";
-export { resolveConfig };
+import { n as resolveConfigFile, t as resolveConfig } from "../../loader-DwF1lM3f.mjs";
+export { resolveConfig, resolveConfigFile };

package/dist/features/messages/index.cjs

@@ -1,5 +1,33 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_hash = require("../../hash-51ce8YiG.cjs");
+//#region src/features/messages/escape.ts
+/**
+* Quoting for text that has to survive a message format unchanged.
+*
+* This lives beside the converter rather than in a transform because it belongs
+* to the format being written, not to the syntax being read. A literal is the
+* same literal whether it came from a template literal or from JSX, and the
+* moment there is a second target format its reserved characters — and the way
+* it spells an escape — are its own.
+*/
+/**
+* Escape literal text so ICU MessageFormat 1 reads it as the text it is.
+*
+* MF1 escapes with an apostrophe: a run wrapped in one is taken literally, and a
+* doubled apostrophe is a single apostrophe. The subtlety is that an apostrophe
+* only opens a quoted run when a character that needs quoting follows it —
+* anything else and the apostrophe is itself literal. So `'#'` is a real escape
+* inside a plural and the three characters `'#'` anywhere else, which is why
+* `hash` has to be told rather than assumed.
+*
+* @param text Literal text as the author wrote it
+* @param hash Whether `#` stands for a number here, i.e. whether some `plural`
+*   or `ordinal` encloses this text
+*/
+function escapeIcuLiteral(text, hash = false) {
+	return text.replace(/'/gu, "''").replace(hash ? /[{}#]+/gu : /[{}]+/gu, (run) => `'${run}'`);
+}
+//#endregion
 //#region src/features/messages/types.ts
 var Base = class {
 	toICUString() {
@@ -20,10 +48,12 @@ var LiteralMessage = class extends Base {
 var ArgumentMessage = class extends Base {
 	identifier;
 	expression;
-	constructor(identifier, expression) {
+	format;
+	constructor(identifier, expression, format) {
 		super();
 		this.identifier = identifier;
 		this.expression = expression;
+		this.format = format;
 	}
 };
 var ElementMessage = class extends Base {
@@ -42,12 +72,14 @@ var ChoiceMessage = class extends Base {
 	identifier;
 	branches;
 	expression;
-	constructor(kind, identifier, branches, expression) {
+	offset;
+	constructor(kind, identifier, branches, expression, offset) {
 		super();
 		this.kind = kind;
 		this.identifier = identifier;
 		this.branches = branches;
 		this.expression = expression;
+		this.offset = offset;
 	}
 };
 var CompositeMessage = class extends Base {
@@ -76,8 +108,13 @@ const AUTO_INCREMENT_IDENTIFIER = Symbol("auto-increment");
 */
 const BRANCH_PATTERN = /^(?:=\d+|[^\p{Pattern_Syntax}\p{Pattern_White_Space}]+)$/u;
 /**
-* The ICU case a branch is written as. A number names an exact value rather
-* than a key, and only `plural` and `ordinal` are allowed to select on one.
+* The ICU case a branch is written as.
+*
+* Under `plural` and `ordinal` a number names an exact value, spelled `=0`, and
+* so is distinct from the CLDR category that would otherwise match it. `select`
+* has no such syntax — its cases are literal string matches, and `=0` there is
+* a parse error — so a numeric key stays bare, where it matches both `0` and
+* `'0'`.
 *
 * Digits are read literally rather than coerced, because everything JavaScript
 * is willing to call a number is not: `''`, `' '`, and `'+0'` all coerce to
@@ -85,8 +122,9 @@ const BRANCH_PATTERN = /^(?:=\d+|[^\p{Pattern_Syntax}\p{Pattern_White_Space}]+)$
 * author's own key out of the catalogue. Anything else stays a key, where the
 * whitespace or punctuation that made it numeric-looking is caught.
 */
-function getBranchCase(identifier) {
+function getBranchCase(kind, identifier) {
 	const key = String(identifier);
+	if (kind === "select") return key;
 	return /^\d+$/u.test(key) ? `=${+key}` : key;
 }
 /**
@@ -100,12 +138,12 @@ function getBranchCase(identifier) {
 */
 function validateBranchIdentifier(kind, identifier) {
 	if (typeof identifier !== "string") return;
-	const branch = getBranchCase(identifier);
+	const branch = getBranchCase(kind, identifier);
 	if (!BRANCH_PATTERN.test(branch)) {
 		const suggestion = suggestBranchIdentifier(identifier);
 		throw new Error(`Invalid ${kind} branch key '${identifier}', an ICU key cannot contain punctuation or whitespace` + (suggestion ? `, try '${suggestion}'` : ""));
 	}
-	if (kind === "select" && branch.startsWith("=")) throw new Error(`Invalid select branch key '${identifier}', a number selects an exact value, which only 'plural' and 'ordinal' accept`);
+	if (kind === "select" && /^=\d+$/u.test(branch)) throw new Error(`Invalid select branch key '${identifier}', an exact value is only meaningful to 'plural' and 'ordinal', write it as '${branch.slice(1)}'`);
 }
 /**
 * The nearest identifier-safe form of a key, so the error names the fix as well
@@ -125,9 +163,28 @@ function assignSequenceIdentifiers(message, sequence = { current: 0 }, equivalen
 		while (reserved.has(identifier)) identifier = `${sequence.current++}`;
 		return identifier;
 	}
+	const numbered = {
+		tags: [],
+		values: []
+	};
+	/**
+	* The number this expression already has, or a fresh one. An anonymous
+	* placeholder is named by its position, so the same value written twice would
+	* otherwise arrive as two names — `{0} x {1}` for one length, which asks a
+	* translator to keep two holes in step and the caller to supply one value
+	* under two props. This is the rule explicit names already follow, where a
+	* repeat is allowed precisely when nothing distinguishes it.
+	*/
+	function number(assigned, expression) {
+		const seen = assigned.find(([e]) => equivalent(e, expression));
+		if (seen) return seen[1];
+		const identifier = next();
+		assigned.push([expression, identifier]);
+		return identifier;
+	}
 	function walk(message) {
 		if (message instanceof ArgumentMessage || message instanceof ElementMessage || message instanceof ChoiceMessage) {
-			if (message.identifier === AUTO_INCREMENT_IDENTIFIER) message.identifier = next();
+			if (message.identifier === AUTO_INCREMENT_IDENTIFIER) message.identifier = number(message instanceof ElementMessage ? numbered.tags : numbered.values, message.expression);
 		}
 		if (message instanceof CompositeMessage || message instanceof ElementMessage) for (const child of message.children) walk(child);
 		if (message instanceof ChoiceMessage) for (const branch of message.branches) {
@@ -167,30 +224,105 @@ function collectAssignedIdentifiers(message, equivalent) {
 //#endregion
 //#region src/features/messages/convert.ts
 function convertMessageToIcu(message) {
-	function internalConvertMessageToIcu(message) {
+	function internalConvertMessageToIcu(message, hash) {
 		switch (true) {
-			case message instanceof LiteralMessage: return String(message.text);
-			case message instanceof ArgumentMessage: return `{${String(message.identifier)}}`;
+			case message instanceof LiteralMessage: return escapeIcuLiteral(String(message.text), hash !== void 0);
+			case message instanceof ArgumentMessage: {
+				if (!message.format && hash !== void 0 && String(message.identifier) === hash) return "#";
+				const parts = [String(message.identifier)];
+				if (message.format) parts.push(message.format.type);
+				if (message.format?.style) parts.push(message.format.style);
+				return `{${parts.join(", ")}}`;
+			}
 			case message instanceof ElementMessage: {
 				if (message.children.length === 0) return `<${String(message.identifier)}/>`;
-				const children = message.children.map((m) => internalConvertMessageToIcu(m)).join("");
+				const children = message.children.map((m) => internalConvertMessageToIcu(m, hash)).join("");
 				return `<${String(message.identifier)}>${children}</${String(message.identifier)}>`;
 			}
 			case message instanceof ChoiceMessage: {
+				const scope = message.kind === "select" ? hash : String(message.identifier);
 				const branches = message.branches.map(({ identifier, value }) => ({
-					identifier: getBranchCase(identifier),
-					value: internalConvertMessageToIcu(value)
+					identifier: getBranchCase(message.kind, identifier),
+					value: internalConvertMessageToIcu(value, scope)
 				})).map(({ identifier, value }) => `  ${identifier} {${value}}\n`).join("");
 				const format = message.kind === "ordinal" ? "selectordinal" : message.kind;
-				return `{${String(message.identifier)}, ${format},\n${branches}}`;
+				const offset = message.offset === void 0 || message.kind === "select" ? "" : ` offset:${message.offset}`;
+				return `{${String(message.identifier)}, ${format},${offset}\n${branches}}`;
 			}
-			case message instanceof CompositeMessage: return Object.entries(message.children).map(([, m]) => internalConvertMessageToIcu(m)).join("");
+			case message instanceof CompositeMessage: return Object.entries(message.children).map(([, m]) => internalConvertMessageToIcu(m, hash)).join("");
 			default: throw new Error("Unknown message type", { cause: message });
 		}
 	}
-	return internalConvertMessageToIcu(message).trim();
+	return internalConvertMessageToIcu(message, void 0).trim();
+}
+//#endregion
+//#region src/features/messages/format.ts
+/**
+* The ICU argument types a macro can author, and the named styles each accepts.
+*
+* `currency` is deliberately absent from `number`. MF1 has nowhere to write the
+* currency code — it comes from the formatter's configuration, not the message
+* — so `{price, number, currency}` formats as a literal `{$price}` at runtime
+* rather than an amount. Currency belongs to number skeletons, which the
+* formatter does not accept yet either.
+*
+* `spellout`, RBNF `ordinal`, and `choice` are absent by decision rather than
+* oversight: the first two are ICU4J/ICU4C rule-based formats with no `Intl`
+* equivalent, and the third is deprecated in ICU itself in favour of `plural`.
+*/
+const ARGUMENT_STYLES = {
+	number: ["integer", "percent"],
+	date: [
+		"short",
+		"medium",
+		"long",
+		"full"
+	],
+	time: [
+		"short",
+		"medium",
+		"long",
+		"full"
+	]
+};
+const ARGUMENT_TYPES = Object.keys(ARGUMENT_STYLES);
+function isArgumentType(kind) {
+	return Object.hasOwn(ARGUMENT_STYLES, kind);
+}
+/**
+* A literal `NumberFormat` pattern, e.g. `#,##0.00`.
+*
+* A pattern has to carry a digit placeholder — `#` or `0` — because that is
+* what makes it a pattern rather than a word. Without that requirement any
+* brace-free string qualifies, which quietly readmits the named styles this
+* module exists to reject: `currency` would sail through as a "pattern" and
+* extract to the `{price, number, currency}` the formatter cannot honour, and
+* so would a plain typo.
+*
+* Braces are excluded separately: ICU reserves them for its own pattern syntax,
+* so a style carrying one would close the argument early and take the rest of
+* the message with it.
+*/
+const LITERAL_STYLE_PATTERN = /^[^{}\r\n]*[#0][^{}\r\n]*$/;
+/**
+* Reject an argument style the formatter cannot honour, while the style is
+* still attached to a file and a line.
+*
+* A style is a bare string in the source and a bare string in the catalogue, so
+* nothing between here and the runtime has an opinion about it. Left unchecked,
+* a typo like `{d, date, meduim}` extracts to a catalogue entry that looks
+* perfectly normal and only misformats once it reaches a user.
+*/
+function validateArgumentStyle(type, style) {
+	const named = ARGUMENT_STYLES[type];
+	if (named.includes(style)) return;
+	if (type === "number" && LITERAL_STYLE_PATTERN.test(style)) return;
+	const expected = named.map((s) => `'${s}'`).join(", ");
+	throw new Error(`Invalid ${type} style '${style}', expected ${expected}` + (type === "number" ? ", or a literal number pattern such as #,##0.00" : ""));
 }
 //#endregion
+exports.ARGUMENT_STYLES = ARGUMENT_STYLES;
+exports.ARGUMENT_TYPES = ARGUMENT_TYPES;
 exports.AUTO_INCREMENT_IDENTIFIER = AUTO_INCREMENT_IDENTIFIER;
 exports.ArgumentMessage = ArgumentMessage;
 exports.ChoiceMessage = ChoiceMessage;
@@ -199,6 +331,9 @@ exports.ElementMessage = ElementMessage;
 exports.LiteralMessage = LiteralMessage;
 exports.assignSequenceIdentifiers = assignSequenceIdentifiers;
 exports.convertMessageToIcu = convertMessageToIcu;
+exports.escapeIcuLiteral = escapeIcuLiteral;
 exports.generateHash = require_hash.generateHash;
 exports.getBranchCase = getBranchCase;
+exports.isArgumentType = isArgumentType;
+exports.validateArgumentStyle = validateArgumentStyle;
 exports.validateBranchIdentifier = validateBranchIdentifier;

package/dist/features/messages/index.d.cts

@@ -1,8 +1,46 @@
+//#region src/features/messages/format.d.ts
+/**
+ * The ICU argument types a macro can author, and the named styles each accepts.
+ *
+ * `currency` is deliberately absent from `number`. MF1 has nowhere to write the
+ * currency code — it comes from the formatter's configuration, not the message
+ * — so `{price, number, currency}` formats as a literal `{$price}` at runtime
+ * rather than an amount. Currency belongs to number skeletons, which the
+ * formatter does not accept yet either.
+ *
+ * `spellout`, RBNF `ordinal`, and `choice` are absent by decision rather than
+ * oversight: the first two are ICU4J/ICU4C rule-based formats with no `Intl`
+ * equivalent, and the third is deprecated in ICU itself in favour of `plural`.
+ */
+declare const ARGUMENT_STYLES: {
+  readonly number: readonly ["integer", "percent"];
+  readonly date: readonly ["short", "medium", "long", "full"];
+  readonly time: readonly ["short", "medium", "long", "full"];
+};
+type ArgumentType = keyof typeof ARGUMENT_STYLES;
+declare const ARGUMENT_TYPES: ArgumentType[];
+declare function isArgumentType(kind: string): kind is ArgumentType;
+/**
+ * Reject an argument style the formatter cannot honour, while the style is
+ * still attached to a file and a line.
+ *
+ * A style is a bare string in the source and a bare string in the catalogue, so
+ * nothing between here and the runtime has an opinion about it. Left unchecked,
+ * a typo like `{d, date, meduim}` extracts to a catalogue entry that looks
+ * perfectly normal and only misformats once it reaches a user.
+ */
+declare function validateArgumentStyle(type: ArgumentType, style: string): void;
+//#endregion
 //#region src/features/messages/identifier.d.ts
 declare const AUTO_INCREMENT_IDENTIFIER: unique symbol;
 /**
- * The ICU case a branch is written as. A number names an exact value rather
- * than a key, and only `plural` and `ordinal` are allowed to select on one.
+ * The ICU case a branch is written as.
+ *
+ * Under `plural` and `ordinal` a number names an exact value, spelled `=0`, and
+ * so is distinct from the CLDR category that would otherwise match it. `select`
+ * has no such syntax — its cases are literal string matches, and `=0` there is
+ * a parse error — so a numeric key stays bare, where it matches both `0` and
+ * `'0'`.
  *
  * Digits are read literally rather than coerced, because everything JavaScript
  * is willing to call a number is not: `''`, `' '`, and `'+0'` all coerce to
@@ -10,7 +48,7 @@ declare const AUTO_INCREMENT_IDENTIFIER: unique symbol;
  * author's own key out of the catalogue. Anything else stays a key, where the
  * whitespace or punctuation that made it numeric-looking is caught.
  */
-declare function getBranchCase(identifier: string | typeof AUTO_INCREMENT_IDENTIFIER): string;
+declare function getBranchCase(kind: string, identifier: string | typeof AUTO_INCREMENT_IDENTIFIER): string;
 /**
  * Reject a branch key ICU cannot express, while the key is still attached to a
  * file and a line.
@@ -40,10 +78,23 @@ declare class LiteralMessage extends Base {
   readonly text: string;
   constructor(text: string);
 }
+/**
+ * An ICU argument type and style, e.g. `{n, number, percent}`. A style is
+ * optional — `{n, number}` is the type's default formatting.
+ *
+ * Both are kept as the ICU strings they are written as, rather than as `Intl`
+ * options, because the catalogue is the source of truth and only the ICU
+ * spelling round-trips back out of it.
+ */
+interface ArgumentFormat {
+  type: ArgumentType;
+  style?: string;
+}
 declare class ArgumentMessage extends Base {
   identifier: string | typeof AUTO_INCREMENT_IDENTIFIER;
   readonly expression: any;
-  constructor(identifier: string | typeof AUTO_INCREMENT_IDENTIFIER, expression: any);
+  readonly format?: ArgumentFormat | undefined;
+  constructor(identifier: string | typeof AUTO_INCREMENT_IDENTIFIER, expression: any, format?: ArgumentFormat | undefined);
 }
 declare class ElementMessage extends Base {
   identifier: string | typeof AUTO_INCREMENT_IDENTIFIER;
@@ -59,10 +110,22 @@ declare class ChoiceMessage extends Base {
     readonly value: Message;
   }[];
   readonly expression: any;
+  /**
+   * Subtracted from the selector before `#` is formatted, so "You and 2
+   * others" can select on a total of three. Only `plural` and `ordinal`
+   * accept one; `select` has no number to offset.
+   */
+  readonly offset?: number | undefined;
   constructor(kind: string, identifier: string | typeof AUTO_INCREMENT_IDENTIFIER, branches: {
     identifier: string | typeof AUTO_INCREMENT_IDENTIFIER;
     readonly value: Message;
-  }[], expression: any);
+  }[], expression: any,
+  /**
+   * Subtracted from the selector before `#` is formatted, so "You and 2
+   * others" can select on a total of three. Only `plural` and `ordinal`
+   * accept one; `select` has no number to offset.
+   */
+  offset?: number | undefined);
 }
 declare class CompositeMessage extends Base {
   readonly descriptor: {
@@ -84,7 +147,33 @@ type Message = LiteralMessage | ArgumentMessage | ElementMessage | ChoiceMessage
 //#region src/features/messages/convert.d.ts
 declare function convertMessageToIcu(message: Message): string;
 //#endregion
+//#region src/features/messages/escape.d.ts
+/**
+ * Quoting for text that has to survive a message format unchanged.
+ *
+ * This lives beside the converter rather than in a transform because it belongs
+ * to the format being written, not to the syntax being read. A literal is the
+ * same literal whether it came from a template literal or from JSX, and the
+ * moment there is a second target format its reserved characters — and the way
+ * it spells an escape — are its own.
+ */
+/**
+ * Escape literal text so ICU MessageFormat 1 reads it as the text it is.
+ *
+ * MF1 escapes with an apostrophe: a run wrapped in one is taken literally, and a
+ * doubled apostrophe is a single apostrophe. The subtlety is that an apostrophe
+ * only opens a quoted run when a character that needs quoting follows it —
+ * anything else and the apostrophe is itself literal. So `'#'` is a real escape
+ * inside a plural and the three characters `'#'` anywhere else, which is why
+ * `hash` has to be told rather than assumed.
+ *
+ * @param text Literal text as the author wrote it
+ * @param hash Whether `#` stands for a number here, i.e. whether some `plural`
+ *   or `ordinal` encloses this text
+ */
+declare function escapeIcuLiteral(text: string, hash?: boolean): string;
+//#endregion
 //#region src/features/messages/hash.d.ts
 declare function generateHash(input: string, context?: string): string;
 //#endregion
-export { AUTO_INCREMENT_IDENTIFIER, ArgumentMessage, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, Message, PlaceholderEquivalence, assignSequenceIdentifiers, convertMessageToIcu, generateHash, getBranchCase, validateBranchIdentifier };
+export { ARGUMENT_STYLES, ARGUMENT_TYPES, AUTO_INCREMENT_IDENTIFIER, ArgumentFormat, ArgumentMessage, ArgumentType, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, Message, PlaceholderEquivalence, assignSequenceIdentifiers, convertMessageToIcu, escapeIcuLiteral, generateHash, getBranchCase, isArgumentType, validateArgumentStyle, validateBranchIdentifier };

package/dist/features/messages/index.d.mts

@@ -1,8 +1,46 @@
+//#region src/features/messages/format.d.ts
+/**
+ * The ICU argument types a macro can author, and the named styles each accepts.
+ *
+ * `currency` is deliberately absent from `number`. MF1 has nowhere to write the
+ * currency code — it comes from the formatter's configuration, not the message
+ * — so `{price, number, currency}` formats as a literal `{$price}` at runtime
+ * rather than an amount. Currency belongs to number skeletons, which the
+ * formatter does not accept yet either.
+ *
+ * `spellout`, RBNF `ordinal`, and `choice` are absent by decision rather than
+ * oversight: the first two are ICU4J/ICU4C rule-based formats with no `Intl`
+ * equivalent, and the third is deprecated in ICU itself in favour of `plural`.
+ */
+declare const ARGUMENT_STYLES: {
+  readonly number: readonly ["integer", "percent"];
+  readonly date: readonly ["short", "medium", "long", "full"];
+  readonly time: readonly ["short", "medium", "long", "full"];
+};
+type ArgumentType = keyof typeof ARGUMENT_STYLES;
+declare const ARGUMENT_TYPES: ArgumentType[];
+declare function isArgumentType(kind: string): kind is ArgumentType;
+/**
+ * Reject an argument style the formatter cannot honour, while the style is
+ * still attached to a file and a line.
+ *
+ * A style is a bare string in the source and a bare string in the catalogue, so
+ * nothing between here and the runtime has an opinion about it. Left unchecked,
+ * a typo like `{d, date, meduim}` extracts to a catalogue entry that looks
+ * perfectly normal and only misformats once it reaches a user.
+ */
+declare function validateArgumentStyle(type: ArgumentType, style: string): void;
+//#endregion
 //#region src/features/messages/identifier.d.ts
 declare const AUTO_INCREMENT_IDENTIFIER: unique symbol;
 /**
- * The ICU case a branch is written as. A number names an exact value rather
- * than a key, and only `plural` and `ordinal` are allowed to select on one.
+ * The ICU case a branch is written as.
+ *
+ * Under `plural` and `ordinal` a number names an exact value, spelled `=0`, and
+ * so is distinct from the CLDR category that would otherwise match it. `select`
+ * has no such syntax — its cases are literal string matches, and `=0` there is
+ * a parse error — so a numeric key stays bare, where it matches both `0` and
+ * `'0'`.
  *
  * Digits are read literally rather than coerced, because everything JavaScript
  * is willing to call a number is not: `''`, `' '`, and `'+0'` all coerce to
@@ -10,7 +48,7 @@ declare const AUTO_INCREMENT_IDENTIFIER: unique symbol;
  * author's own key out of the catalogue. Anything else stays a key, where the
  * whitespace or punctuation that made it numeric-looking is caught.
  */
-declare function getBranchCase(identifier: string | typeof AUTO_INCREMENT_IDENTIFIER): string;
+declare function getBranchCase(kind: string, identifier: string | typeof AUTO_INCREMENT_IDENTIFIER): string;
 /**
  * Reject a branch key ICU cannot express, while the key is still attached to a
  * file and a line.
@@ -40,10 +78,23 @@ declare class LiteralMessage extends Base {
   readonly text: string;
   constructor(text: string);
 }
+/**
+ * An ICU argument type and style, e.g. `{n, number, percent}`. A style is
+ * optional — `{n, number}` is the type's default formatting.
+ *
+ * Both are kept as the ICU strings they are written as, rather than as `Intl`
+ * options, because the catalogue is the source of truth and only the ICU
+ * spelling round-trips back out of it.
+ */
+interface ArgumentFormat {
+  type: ArgumentType;
+  style?: string;
+}
 declare class ArgumentMessage extends Base {
   identifier: string | typeof AUTO_INCREMENT_IDENTIFIER;
   readonly expression: any;
-  constructor(identifier: string | typeof AUTO_INCREMENT_IDENTIFIER, expression: any);
+  readonly format?: ArgumentFormat | undefined;
+  constructor(identifier: string | typeof AUTO_INCREMENT_IDENTIFIER, expression: any, format?: ArgumentFormat | undefined);
 }
 declare class ElementMessage extends Base {
   identifier: string | typeof AUTO_INCREMENT_IDENTIFIER;
@@ -59,10 +110,22 @@ declare class ChoiceMessage extends Base {
     readonly value: Message;
   }[];
   readonly expression: any;
+  /**
+   * Subtracted from the selector before `#` is formatted, so "You and 2
+   * others" can select on a total of three. Only `plural` and `ordinal`
+   * accept one; `select` has no number to offset.
+   */
+  readonly offset?: number | undefined;
   constructor(kind: string, identifier: string | typeof AUTO_INCREMENT_IDENTIFIER, branches: {
     identifier: string | typeof AUTO_INCREMENT_IDENTIFIER;
     readonly value: Message;
-  }[], expression: any);
+  }[], expression: any,
+  /**
+   * Subtracted from the selector before `#` is formatted, so "You and 2
+   * others" can select on a total of three. Only `plural` and `ordinal`
+   * accept one; `select` has no number to offset.
+   */
+  offset?: number | undefined);
 }
 declare class CompositeMessage extends Base {
   readonly descriptor: {
@@ -84,7 +147,33 @@ type Message = LiteralMessage | ArgumentMessage | ElementMessage | ChoiceMessage
 //#region src/features/messages/convert.d.ts
 declare function convertMessageToIcu(message: Message): string;
 //#endregion
+//#region src/features/messages/escape.d.ts
+/**
+ * Quoting for text that has to survive a message format unchanged.
+ *
+ * This lives beside the converter rather than in a transform because it belongs
+ * to the format being written, not to the syntax being read. A literal is the
+ * same literal whether it came from a template literal or from JSX, and the
+ * moment there is a second target format its reserved characters — and the way
+ * it spells an escape — are its own.
+ */
+/**
+ * Escape literal text so ICU MessageFormat 1 reads it as the text it is.
+ *
+ * MF1 escapes with an apostrophe: a run wrapped in one is taken literally, and a
+ * doubled apostrophe is a single apostrophe. The subtlety is that an apostrophe
+ * only opens a quoted run when a character that needs quoting follows it —
+ * anything else and the apostrophe is itself literal. So `'#'` is a real escape
+ * inside a plural and the three characters `'#'` anywhere else, which is why
+ * `hash` has to be told rather than assumed.
+ *
+ * @param text Literal text as the author wrote it
+ * @param hash Whether `#` stands for a number here, i.e. whether some `plural`
+ *   or `ordinal` encloses this text
+ */
+declare function escapeIcuLiteral(text: string, hash?: boolean): string;
+//#endregion
 //#region src/features/messages/hash.d.ts
 declare function generateHash(input: string, context?: string): string;
 //#endregion
-export { AUTO_INCREMENT_IDENTIFIER, ArgumentMessage, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, Message, PlaceholderEquivalence, assignSequenceIdentifiers, convertMessageToIcu, generateHash, getBranchCase, validateBranchIdentifier };
+export { ARGUMENT_STYLES, ARGUMENT_TYPES, AUTO_INCREMENT_IDENTIFIER, ArgumentFormat, ArgumentMessage, ArgumentType, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, Message, PlaceholderEquivalence, assignSequenceIdentifiers, convertMessageToIcu, escapeIcuLiteral, generateHash, getBranchCase, isArgumentType, validateArgumentStyle, validateBranchIdentifier };

package/dist/features/messages/index.mjs

@@ -1,4 +1,32 @@
 import { t as generateHash } from "../../hash-DvzpieJD.mjs";
+//#region src/features/messages/escape.ts
+/**
+* Quoting for text that has to survive a message format unchanged.
+*
+* This lives beside the converter rather than in a transform because it belongs
+* to the format being written, not to the syntax being read. A literal is the
+* same literal whether it came from a template literal or from JSX, and the
+* moment there is a second target format its reserved characters — and the way
+* it spells an escape — are its own.
+*/
+/**
+* Escape literal text so ICU MessageFormat 1 reads it as the text it is.
+*
+* MF1 escapes with an apostrophe: a run wrapped in one is taken literally, and a
+* doubled apostrophe is a single apostrophe. The subtlety is that an apostrophe
+* only opens a quoted run when a character that needs quoting follows it —
+* anything else and the apostrophe is itself literal. So `'#'` is a real escape
+* inside a plural and the three characters `'#'` anywhere else, which is why
+* `hash` has to be told rather than assumed.
+*
+* @param text Literal text as the author wrote it
+* @param hash Whether `#` stands for a number here, i.e. whether some `plural`
+*   or `ordinal` encloses this text
+*/
+function escapeIcuLiteral(text, hash = false) {
+	return text.replace(/'/gu, "''").replace(hash ? /[{}#]+/gu : /[{}]+/gu, (run) => `'${run}'`);
+}
+//#endregion
 //#region src/features/messages/types.ts
 var Base = class {
 	toICUString() {
@@ -19,10 +47,12 @@ var LiteralMessage = class extends Base {
 var ArgumentMessage = class extends Base {
 	identifier;
 	expression;
-	constructor(identifier, expression) {
+	format;
+	constructor(identifier, expression, format) {
 		super();
 		this.identifier = identifier;
 		this.expression = expression;
+		this.format = format;
 	}
 };
 var ElementMessage = class extends Base {
@@ -41,12 +71,14 @@ var ChoiceMessage = class extends Base {
 	identifier;
 	branches;
 	expression;
-	constructor(kind, identifier, branches, expression) {
+	offset;
+	constructor(kind, identifier, branches, expression, offset) {
 		super();
 		this.kind = kind;
 		this.identifier = identifier;
 		this.branches = branches;
 		this.expression = expression;
+		this.offset = offset;
 	}
 };
 var CompositeMessage = class extends Base {
@@ -75,8 +107,13 @@ const AUTO_INCREMENT_IDENTIFIER = Symbol("auto-increment");
 */
 const BRANCH_PATTERN = /^(?:=\d+|[^\p{Pattern_Syntax}\p{Pattern_White_Space}]+)$/u;
 /**
-* The ICU case a branch is written as. A number names an exact value rather
-* than a key, and only `plural` and `ordinal` are allowed to select on one.
+* The ICU case a branch is written as.
+*
+* Under `plural` and `ordinal` a number names an exact value, spelled `=0`, and
+* so is distinct from the CLDR category that would otherwise match it. `select`
+* has no such syntax — its cases are literal string matches, and `=0` there is
+* a parse error — so a numeric key stays bare, where it matches both `0` and
+* `'0'`.
 *
 * Digits are read literally rather than coerced, because everything JavaScript
 * is willing to call a number is not: `''`, `' '`, and `'+0'` all coerce to
@@ -84,8 +121,9 @@ const BRANCH_PATTERN = /^(?:=\d+|[^\p{Pattern_Syntax}\p{Pattern_White_Space}]+)$
 * author's own key out of the catalogue. Anything else stays a key, where the
 * whitespace or punctuation that made it numeric-looking is caught.
 */
-function getBranchCase(identifier) {
+function getBranchCase(kind, identifier) {
 	const key = String(identifier);
+	if (kind === "select") return key;
 	return /^\d+$/u.test(key) ? `=${+key}` : key;
 }
 /**
@@ -99,12 +137,12 @@ function getBranchCase(identifier) {
 */
 function validateBranchIdentifier(kind, identifier) {
 	if (typeof identifier !== "string") return;
-	const branch = getBranchCase(identifier);
+	const branch = getBranchCase(kind, identifier);
 	if (!BRANCH_PATTERN.test(branch)) {
 		const suggestion = suggestBranchIdentifier(identifier);
 		throw new Error(`Invalid ${kind} branch key '${identifier}', an ICU key cannot contain punctuation or whitespace` + (suggestion ? `, try '${suggestion}'` : ""));
 	}
-	if (kind === "select" && branch.startsWith("=")) throw new Error(`Invalid select branch key '${identifier}', a number selects an exact value, which only 'plural' and 'ordinal' accept`);
+	if (kind === "select" && /^=\d+$/u.test(branch)) throw new Error(`Invalid select branch key '${identifier}', an exact value is only meaningful to 'plural' and 'ordinal', write it as '${branch.slice(1)}'`);
 }
 /**
 * The nearest identifier-safe form of a key, so the error names the fix as well
@@ -124,9 +162,28 @@ function assignSequenceIdentifiers(message, sequence = { current: 0 }, equivalen
 		while (reserved.has(identifier)) identifier = `${sequence.current++}`;
 		return identifier;
 	}
+	const numbered = {
+		tags: [],
+		values: []
+	};
+	/**
+	* The number this expression already has, or a fresh one. An anonymous
+	* placeholder is named by its position, so the same value written twice would
+	* otherwise arrive as two names — `{0} x {1}` for one length, which asks a
+	* translator to keep two holes in step and the caller to supply one value
+	* under two props. This is the rule explicit names already follow, where a
+	* repeat is allowed precisely when nothing distinguishes it.
+	*/
+	function number(assigned, expression) {
+		const seen = assigned.find(([e]) => equivalent(e, expression));
+		if (seen) return seen[1];
+		const identifier = next();
+		assigned.push([expression, identifier]);
+		return identifier;
+	}
 	function walk(message) {
 		if (message instanceof ArgumentMessage || message instanceof ElementMessage || message instanceof ChoiceMessage) {
-			if (message.identifier === AUTO_INCREMENT_IDENTIFIER) message.identifier = next();
+			if (message.identifier === AUTO_INCREMENT_IDENTIFIER) message.identifier = number(message instanceof ElementMessage ? numbered.tags : numbered.values, message.expression);
 		}
 		if (message instanceof CompositeMessage || message instanceof ElementMessage) for (const child of message.children) walk(child);
 		if (message instanceof ChoiceMessage) for (const branch of message.branches) {
@@ -166,28 +223,101 @@ function collectAssignedIdentifiers(message, equivalent) {
 //#endregion
 //#region src/features/messages/convert.ts
 function convertMessageToIcu(message) {
-	function internalConvertMessageToIcu(message) {
+	function internalConvertMessageToIcu(message, hash) {
 		switch (true) {
-			case message instanceof LiteralMessage: return String(message.text);
-			case message instanceof ArgumentMessage: return `{${String(message.identifier)}}`;
+			case message instanceof LiteralMessage: return escapeIcuLiteral(String(message.text), hash !== void 0);
+			case message instanceof ArgumentMessage: {
+				if (!message.format && hash !== void 0 && String(message.identifier) === hash) return "#";
+				const parts = [String(message.identifier)];
+				if (message.format) parts.push(message.format.type);
+				if (message.format?.style) parts.push(message.format.style);
+				return `{${parts.join(", ")}}`;
+			}
 			case message instanceof ElementMessage: {
 				if (message.children.length === 0) return `<${String(message.identifier)}/>`;
-				const children = message.children.map((m) => internalConvertMessageToIcu(m)).join("");
+				const children = message.children.map((m) => internalConvertMessageToIcu(m, hash)).join("");
 				return `<${String(message.identifier)}>${children}</${String(message.identifier)}>`;
 			}
 			case message instanceof ChoiceMessage: {
+				const scope = message.kind === "select" ? hash : String(message.identifier);
 				const branches = message.branches.map(({ identifier, value }) => ({
-					identifier: getBranchCase(identifier),
-					value: internalConvertMessageToIcu(value)
+					identifier: getBranchCase(message.kind, identifier),
+					value: internalConvertMessageToIcu(value, scope)
 				})).map(({ identifier, value }) => `  ${identifier} {${value}}\n`).join("");
 				const format = message.kind === "ordinal" ? "selectordinal" : message.kind;
-				return `{${String(message.identifier)}, ${format},\n${branches}}`;
+				const offset = message.offset === void 0 || message.kind === "select" ? "" : ` offset:${message.offset}`;
+				return `{${String(message.identifier)}, ${format},${offset}\n${branches}}`;
 			}
-			case message instanceof CompositeMessage: return Object.entries(message.children).map(([, m]) => internalConvertMessageToIcu(m)).join("");
+			case message instanceof CompositeMessage: return Object.entries(message.children).map(([, m]) => internalConvertMessageToIcu(m, hash)).join("");
 			default: throw new Error("Unknown message type", { cause: message });
 		}
 	}
-	return internalConvertMessageToIcu(message).trim();
+	return internalConvertMessageToIcu(message, void 0).trim();
+}
+//#endregion
+//#region src/features/messages/format.ts
+/**
+* The ICU argument types a macro can author, and the named styles each accepts.
+*
+* `currency` is deliberately absent from `number`. MF1 has nowhere to write the
+* currency code — it comes from the formatter's configuration, not the message
+* — so `{price, number, currency}` formats as a literal `{$price}` at runtime
+* rather than an amount. Currency belongs to number skeletons, which the
+* formatter does not accept yet either.
+*
+* `spellout`, RBNF `ordinal`, and `choice` are absent by decision rather than
+* oversight: the first two are ICU4J/ICU4C rule-based formats with no `Intl`
+* equivalent, and the third is deprecated in ICU itself in favour of `plural`.
+*/
+const ARGUMENT_STYLES = {
+	number: ["integer", "percent"],
+	date: [
+		"short",
+		"medium",
+		"long",
+		"full"
+	],
+	time: [
+		"short",
+		"medium",
+		"long",
+		"full"
+	]
+};
+const ARGUMENT_TYPES = Object.keys(ARGUMENT_STYLES);
+function isArgumentType(kind) {
+	return Object.hasOwn(ARGUMENT_STYLES, kind);
+}
+/**
+* A literal `NumberFormat` pattern, e.g. `#,##0.00`.
+*
+* A pattern has to carry a digit placeholder — `#` or `0` — because that is
+* what makes it a pattern rather than a word. Without that requirement any
+* brace-free string qualifies, which quietly readmits the named styles this
+* module exists to reject: `currency` would sail through as a "pattern" and
+* extract to the `{price, number, currency}` the formatter cannot honour, and
+* so would a plain typo.
+*
+* Braces are excluded separately: ICU reserves them for its own pattern syntax,
+* so a style carrying one would close the argument early and take the rest of
+* the message with it.
+*/
+const LITERAL_STYLE_PATTERN = /^[^{}\r\n]*[#0][^{}\r\n]*$/;
+/**
+* Reject an argument style the formatter cannot honour, while the style is
+* still attached to a file and a line.
+*
+* A style is a bare string in the source and a bare string in the catalogue, so
+* nothing between here and the runtime has an opinion about it. Left unchecked,
+* a typo like `{d, date, meduim}` extracts to a catalogue entry that looks
+* perfectly normal and only misformats once it reaches a user.
+*/
+function validateArgumentStyle(type, style) {
+	const named = ARGUMENT_STYLES[type];
+	if (named.includes(style)) return;
+	if (type === "number" && LITERAL_STYLE_PATTERN.test(style)) return;
+	const expected = named.map((s) => `'${s}'`).join(", ");
+	throw new Error(`Invalid ${type} style '${style}', expected ${expected}` + (type === "number" ? ", or a literal number pattern such as #,##0.00" : ""));
 }
 //#endregion
-export { AUTO_INCREMENT_IDENTIFIER, ArgumentMessage, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, assignSequenceIdentifiers, convertMessageToIcu, generateHash, getBranchCase, validateBranchIdentifier };
+export { ARGUMENT_STYLES, ARGUMENT_TYPES, AUTO_INCREMENT_IDENTIFIER, ArgumentMessage, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, assignSequenceIdentifiers, convertMessageToIcu, escapeIcuLiteral, generateHash, getBranchCase, isArgumentType, validateArgumentStyle, validateBranchIdentifier };

package/dist/{loader-A1uS7qkK.cjs → loader-BdCeoj3-.cjs}

@@ -73,13 +73,22 @@ const configLoaders = Object.freeze({
 });
 //#endregion
 //#region src/features/loader/resolve.ts
-function resolveConfig(name = "saykit") {
+/**
+* The config file {@link resolveConfig} would load, for callers that need the
+* path itself rather than its contents — salting a bundler's cache key with it,
+* for one, since what a catalogue assembles into depends on the config.
+*/
+function resolveConfigFile(name = "saykit") {
 	const file = findConfigFile(name, process.cwd());
 	if (!file) throw new Error(`Could not find config file for "${name}"`);
-	const ext = (0, node_path.extname)(file.id).toLowerCase();
+	return file.id;
+}
+function resolveConfig(name = "saykit") {
+	const id = resolveConfigFile(name);
+	const ext = (0, node_path.extname)(id).toLowerCase();
 	const load = ext in configLoaders ? configLoaders[ext] : null;
 	if (!load) throw new Error(`Unsupported config file type "${ext}" for "${name}"`);
-	const config = load(file.id);
+	const config = load(id);
 	if (!config || typeof config !== "object") throw new Error(`Invalid config file for "${name}"`);
 	return config;
 }
@@ -90,3 +99,9 @@ Object.defineProperty(exports, "resolveConfig", {
 		return resolveConfig;
 	}
 });
+Object.defineProperty(exports, "resolveConfigFile", {
+	enumerable: true,
+	get: function() {
+		return resolveConfigFile;
+	}
+});

package/dist/{loader-DLyuZzF2.mjs → loader-DwF1lM3f.mjs}

@@ -73,15 +73,24 @@ const configLoaders = Object.freeze({
 });
 //#endregion
 //#region src/features/loader/resolve.ts
-function resolveConfig(name = "saykit") {
+/**
+* The config file {@link resolveConfig} would load, for callers that need the
+* path itself rather than its contents — salting a bundler's cache key with it,
+* for one, since what a catalogue assembles into depends on the config.
+*/
+function resolveConfigFile(name = "saykit") {
 	const file = findConfigFile(name, process.cwd());
 	if (!file) throw new Error(`Could not find config file for "${name}"`);
-	const ext = extname(file.id).toLowerCase();
+	return file.id;
+}
+function resolveConfig(name = "saykit") {
+	const id = resolveConfigFile(name);
+	const ext = extname(id).toLowerCase();
 	const load = ext in configLoaders ? configLoaders[ext] : null;
 	if (!load) throw new Error(`Unsupported config file type "${ext}" for "${name}"`);
-	const config = load(file.id);
+	const config = load(id);
 	if (!config || typeof config !== "object") throw new Error(`Invalid config file for "${name}"`);
 	return config;
 }
 //#endregion
-export { resolveConfig as t };
+export { resolveConfigFile as n, resolveConfig as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/config",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "CLI and configuration tooling for saykit",
   "keywords": [
     "cli",