@saykit/config 0.6.0 → 0.7.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,54 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_hash = require("../../hash-51ce8YiG.cjs");
-//#region src/features/messages/identifier.ts
-const AUTO_INCREMENT_IDENTIFIER = Symbol("auto-increment");
-function assignSequenceIdentifiers(message, sequence = { current: 0 }, equivalent = () => false) {
-	const reserved = collectAssignedIdentifiers(message, equivalent);
-	function next() {
-		let identifier = `${sequence.current++}`;
-		while (reserved.has(identifier)) identifier = `${sequence.current++}`;
-		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 instanceof CompositeMessage || message instanceof ElementMessage) for (const child of message.children) walk(child);
-		if (message instanceof ChoiceMessage) for (const branch of message.branches) {
-			if (branch.identifier === AUTO_INCREMENT_IDENTIFIER) branch.identifier = next();
-			walk(branch.value);
-		}
-	}
-	walk(message);
-}
-/**
-* Collect the identifiers already assigned before this pass runs, so generated
-* sequence numbers never shadow an explicit one (e.g. an element tagged `0`).
-*
-* A name is claimed by what produced it, not by the name alone. Two that differ
-* each compile to their own prop, and a translator moving them around a sentence
-* has to be able to tell them apart, so they are a build error. Repeats are fine
-* when nothing distinguishes them: the same variable interpolated twice is one
-* value, and two identical elements are one tag.
-*/
-function collectAssignedIdentifiers(message, equivalent) {
-	const tags = /* @__PURE__ */ new Map();
-	const values = /* @__PURE__ */ new Map();
-	function claim(claimed, identifier, expression, conflict) {
-		if (claimed.has(identifier) && !equivalent(claimed.get(identifier), expression)) throw new Error(conflict);
-		claimed.set(identifier, expression);
-	}
-	function walk(message) {
-		if (message instanceof ElementMessage && typeof message.identifier === "string") claim(tags, message.identifier, message.expression, `Duplicate element tag '${message.identifier}', give each element in a message its own tag unless they are identical`);
-		if ((message instanceof ArgumentMessage || message instanceof ChoiceMessage) && typeof message.identifier === "string") claim(values, message.identifier, message.expression, `Duplicate placeholder name '${message.identifier}', give each value in a message its own name unless they are identical`);
-		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) walk(branch.value);
-	}
-	walk(message);
-	for (const tag of tags.keys()) if (values.has(tag)) throw new Error(`Element tag '${tag}' collides with an argument of the same name`);
-	return /* @__PURE__ */ new Set([...tags.keys(), ...values.keys()]);
-}
-//#endregion
 //#region src/features/messages/types.ts
 var Base = class {
 	toICUString() {
@@ -69,10 +20,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 {
@@ -91,12 +44,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 {
@@ -117,12 +72,120 @@ var CompositeMessage = class extends Base {
 	}
 };
 //#endregion
+//#region src/features/messages/identifier.ts
+const AUTO_INCREMENT_IDENTIFIER = Symbol("auto-increment");
+/**
+* An ICU case, either an exact value or a key. ICU reserves its own pattern
+* syntax, so a key carries no punctuation and no whitespace.
+*/
+const BRANCH_PATTERN = /^(?:=\d+|[^\p{Pattern_Syntax}\p{Pattern_White_Space}]+)$/u;
+/**
+* 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
+* `=0`, which would pass for a key that selects zero and quietly leave the
+* 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(kind, identifier) {
+	const key = String(identifier);
+	if (kind === "select") return key;
+	return /^\d+$/u.test(key) ? `=${+key}` : key;
+}
+/**
+* Reject a branch key ICU cannot express, while the key is still attached to a
+* file and a line.
+*
+* A hyphenated string union is ordinary application code and typechecks,
+* builds, and extracts to a catalogue entry that looks perfectly normal — the
+* only sign of trouble is a parse error at format time, in a message whose
+* source is long gone.
+*/
+function validateBranchIdentifier(kind, identifier) {
+	if (typeof identifier !== "string") return;
+	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" && /^=\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
+* as the problem. The constraint comes from ICU rather than from anything the
+* author wrote, and camel case is how the rest of the codebase already spells a
+* name of more than one word.
+*/
+function suggestBranchIdentifier(identifier) {
+	const suggestion = identifier.split(/[^\p{L}\p{N}]+/u).filter(Boolean).map((word, index) => index === 0 ? word : word[0].toUpperCase() + word.slice(1)).join("");
+	if (!BRANCH_PATTERN.test(suggestion) || !Number.isNaN(+suggestion)) return void 0;
+	return suggestion;
+}
+function assignSequenceIdentifiers(message, sequence = { current: 0 }, equivalent = () => false) {
+	const reserved = collectAssignedIdentifiers(message, equivalent);
+	function next() {
+		let identifier = `${sequence.current++}`;
+		while (reserved.has(identifier)) identifier = `${sequence.current++}`;
+		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 instanceof CompositeMessage || message instanceof ElementMessage) for (const child of message.children) walk(child);
+		if (message instanceof ChoiceMessage) for (const branch of message.branches) {
+			if (branch.identifier === AUTO_INCREMENT_IDENTIFIER) branch.identifier = next();
+			walk(branch.value);
+		}
+	}
+	walk(message);
+}
+/**
+* Collect the identifiers already assigned before this pass runs, so generated
+* sequence numbers never shadow an explicit one (e.g. an element tagged `0`).
+*
+* A name is claimed by what produced it, not by the name alone. Two that differ
+* each compile to their own prop, and a translator moving them around a sentence
+* has to be able to tell them apart, so they are a build error. Repeats are fine
+* when nothing distinguishes them: the same variable interpolated twice is one
+* value, and two identical elements are one tag.
+*/
+function collectAssignedIdentifiers(message, equivalent) {
+	const tags = /* @__PURE__ */ new Map();
+	const values = /* @__PURE__ */ new Map();
+	function claim(claimed, identifier, expression, conflict) {
+		if (claimed.has(identifier) && !equivalent(claimed.get(identifier), expression)) throw new Error(conflict);
+		claimed.set(identifier, expression);
+	}
+	function walk(message) {
+		if (message instanceof ElementMessage && typeof message.identifier === "string") claim(tags, message.identifier, message.expression, `Duplicate element tag '${message.identifier}', give each element in a message its own tag unless they are identical`);
+		if ((message instanceof ArgumentMessage || message instanceof ChoiceMessage) && typeof message.identifier === "string") claim(values, message.identifier, message.expression, `Duplicate placeholder name '${message.identifier}', give each value in a message its own name unless they are identical`);
+		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) walk(branch.value);
+	}
+	walk(message);
+	for (const tag of tags.keys()) if (values.has(tag)) throw new Error(`Element tag '${tag}' collides with an argument of the same name`);
+	return /* @__PURE__ */ new Set([...tags.keys(), ...values.keys()]);
+}
+//#endregion
 //#region src/features/messages/convert.ts
 function convertMessageToIcu(message) {
 	function internalConvertMessageToIcu(message) {
 		switch (true) {
 			case message instanceof LiteralMessage: return String(message.text);
-			case message instanceof ArgumentMessage: return `{${String(message.identifier)}}`;
+			case message instanceof ArgumentMessage: {
+				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("");
@@ -130,11 +193,12 @@ function convertMessageToIcu(message) {
 			}
 			case message instanceof ChoiceMessage: {
 				const branches = message.branches.map(({ identifier, value }) => ({
-					identifier: Number.isNaN(+String(identifier)) ? String(identifier) : `=${+String(identifier)}`,
+					identifier: getBranchCase(message.kind, identifier),
 					value: internalConvertMessageToIcu(value)
 				})).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("");
 			default: throw new Error("Unknown message type", { cause: message });
@@ -143,6 +207,73 @@ function convertMessageToIcu(message) {
 	return internalConvertMessageToIcu(message).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;
@@ -152,3 +283,7 @@ exports.LiteralMessage = LiteralMessage;
 exports.assignSequenceIdentifiers = assignSequenceIdentifiers;
 exports.convertMessageToIcu = convertMessageToIcu;
 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,5 +1,64 @@
+//#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.
+ *
+ * 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
+ * `=0`, which would pass for a key that selects zero and quietly leave the
+ * 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(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.
+ *
+ * A hyphenated string union is ordinary application code and typechecks,
+ * builds, and extracts to a catalogue entry that looks perfectly normal — the
+ * only sign of trouble is a parse error at format time, in a message whose
+ * source is long gone.
+ */
+declare function validateBranchIdentifier(kind: string, identifier: string | typeof AUTO_INCREMENT_IDENTIFIER): void;
 /**
  * Decides whether two placeholders sharing a name are the same placeholder, and
  * so may share it. Only the syntax that produced them can answer that, so the
@@ -19,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;
@@ -38,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: {
@@ -66,4 +150,4 @@ declare function convertMessageToIcu(message: Message): string;
 //#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 };
+export { ARGUMENT_STYLES, ARGUMENT_TYPES, AUTO_INCREMENT_IDENTIFIER, ArgumentFormat, ArgumentMessage, ArgumentType, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, Message, PlaceholderEquivalence, assignSequenceIdentifiers, convertMessageToIcu, generateHash, getBranchCase, isArgumentType, validateArgumentStyle, validateBranchIdentifier };

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

@@ -1,5 +1,64 @@
+//#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.
+ *
+ * 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
+ * `=0`, which would pass for a key that selects zero and quietly leave the
+ * 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(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.
+ *
+ * A hyphenated string union is ordinary application code and typechecks,
+ * builds, and extracts to a catalogue entry that looks perfectly normal — the
+ * only sign of trouble is a parse error at format time, in a message whose
+ * source is long gone.
+ */
+declare function validateBranchIdentifier(kind: string, identifier: string | typeof AUTO_INCREMENT_IDENTIFIER): void;
 /**
  * Decides whether two placeholders sharing a name are the same placeholder, and
  * so may share it. Only the syntax that produced them can answer that, so the
@@ -19,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;
@@ -38,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: {
@@ -66,4 +150,4 @@ declare function convertMessageToIcu(message: Message): string;
 //#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 };
+export { ARGUMENT_STYLES, ARGUMENT_TYPES, AUTO_INCREMENT_IDENTIFIER, ArgumentFormat, ArgumentMessage, ArgumentType, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, Message, PlaceholderEquivalence, assignSequenceIdentifiers, convertMessageToIcu, generateHash, getBranchCase, isArgumentType, validateArgumentStyle, validateBranchIdentifier };

package/dist/features/messages/index.mjs

@@ -1,53 +1,4 @@
 import { t as generateHash } from "../../hash-DvzpieJD.mjs";
-//#region src/features/messages/identifier.ts
-const AUTO_INCREMENT_IDENTIFIER = Symbol("auto-increment");
-function assignSequenceIdentifiers(message, sequence = { current: 0 }, equivalent = () => false) {
-	const reserved = collectAssignedIdentifiers(message, equivalent);
-	function next() {
-		let identifier = `${sequence.current++}`;
-		while (reserved.has(identifier)) identifier = `${sequence.current++}`;
-		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 instanceof CompositeMessage || message instanceof ElementMessage) for (const child of message.children) walk(child);
-		if (message instanceof ChoiceMessage) for (const branch of message.branches) {
-			if (branch.identifier === AUTO_INCREMENT_IDENTIFIER) branch.identifier = next();
-			walk(branch.value);
-		}
-	}
-	walk(message);
-}
-/**
-* Collect the identifiers already assigned before this pass runs, so generated
-* sequence numbers never shadow an explicit one (e.g. an element tagged `0`).
-*
-* A name is claimed by what produced it, not by the name alone. Two that differ
-* each compile to their own prop, and a translator moving them around a sentence
-* has to be able to tell them apart, so they are a build error. Repeats are fine
-* when nothing distinguishes them: the same variable interpolated twice is one
-* value, and two identical elements are one tag.
-*/
-function collectAssignedIdentifiers(message, equivalent) {
-	const tags = /* @__PURE__ */ new Map();
-	const values = /* @__PURE__ */ new Map();
-	function claim(claimed, identifier, expression, conflict) {
-		if (claimed.has(identifier) && !equivalent(claimed.get(identifier), expression)) throw new Error(conflict);
-		claimed.set(identifier, expression);
-	}
-	function walk(message) {
-		if (message instanceof ElementMessage && typeof message.identifier === "string") claim(tags, message.identifier, message.expression, `Duplicate element tag '${message.identifier}', give each element in a message its own tag unless they are identical`);
-		if ((message instanceof ArgumentMessage || message instanceof ChoiceMessage) && typeof message.identifier === "string") claim(values, message.identifier, message.expression, `Duplicate placeholder name '${message.identifier}', give each value in a message its own name unless they are identical`);
-		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) walk(branch.value);
-	}
-	walk(message);
-	for (const tag of tags.keys()) if (values.has(tag)) throw new Error(`Element tag '${tag}' collides with an argument of the same name`);
-	return /* @__PURE__ */ new Set([...tags.keys(), ...values.keys()]);
-}
-//#endregion
 //#region src/features/messages/types.ts
 var Base = class {
 	toICUString() {
@@ -68,10 +19,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 {
@@ -90,12 +43,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 {
@@ -116,12 +71,120 @@ var CompositeMessage = class extends Base {
 	}
 };
 //#endregion
+//#region src/features/messages/identifier.ts
+const AUTO_INCREMENT_IDENTIFIER = Symbol("auto-increment");
+/**
+* An ICU case, either an exact value or a key. ICU reserves its own pattern
+* syntax, so a key carries no punctuation and no whitespace.
+*/
+const BRANCH_PATTERN = /^(?:=\d+|[^\p{Pattern_Syntax}\p{Pattern_White_Space}]+)$/u;
+/**
+* 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
+* `=0`, which would pass for a key that selects zero and quietly leave the
+* 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(kind, identifier) {
+	const key = String(identifier);
+	if (kind === "select") return key;
+	return /^\d+$/u.test(key) ? `=${+key}` : key;
+}
+/**
+* Reject a branch key ICU cannot express, while the key is still attached to a
+* file and a line.
+*
+* A hyphenated string union is ordinary application code and typechecks,
+* builds, and extracts to a catalogue entry that looks perfectly normal — the
+* only sign of trouble is a parse error at format time, in a message whose
+* source is long gone.
+*/
+function validateBranchIdentifier(kind, identifier) {
+	if (typeof identifier !== "string") return;
+	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" && /^=\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
+* as the problem. The constraint comes from ICU rather than from anything the
+* author wrote, and camel case is how the rest of the codebase already spells a
+* name of more than one word.
+*/
+function suggestBranchIdentifier(identifier) {
+	const suggestion = identifier.split(/[^\p{L}\p{N}]+/u).filter(Boolean).map((word, index) => index === 0 ? word : word[0].toUpperCase() + word.slice(1)).join("");
+	if (!BRANCH_PATTERN.test(suggestion) || !Number.isNaN(+suggestion)) return void 0;
+	return suggestion;
+}
+function assignSequenceIdentifiers(message, sequence = { current: 0 }, equivalent = () => false) {
+	const reserved = collectAssignedIdentifiers(message, equivalent);
+	function next() {
+		let identifier = `${sequence.current++}`;
+		while (reserved.has(identifier)) identifier = `${sequence.current++}`;
+		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 instanceof CompositeMessage || message instanceof ElementMessage) for (const child of message.children) walk(child);
+		if (message instanceof ChoiceMessage) for (const branch of message.branches) {
+			if (branch.identifier === AUTO_INCREMENT_IDENTIFIER) branch.identifier = next();
+			walk(branch.value);
+		}
+	}
+	walk(message);
+}
+/**
+* Collect the identifiers already assigned before this pass runs, so generated
+* sequence numbers never shadow an explicit one (e.g. an element tagged `0`).
+*
+* A name is claimed by what produced it, not by the name alone. Two that differ
+* each compile to their own prop, and a translator moving them around a sentence
+* has to be able to tell them apart, so they are a build error. Repeats are fine
+* when nothing distinguishes them: the same variable interpolated twice is one
+* value, and two identical elements are one tag.
+*/
+function collectAssignedIdentifiers(message, equivalent) {
+	const tags = /* @__PURE__ */ new Map();
+	const values = /* @__PURE__ */ new Map();
+	function claim(claimed, identifier, expression, conflict) {
+		if (claimed.has(identifier) && !equivalent(claimed.get(identifier), expression)) throw new Error(conflict);
+		claimed.set(identifier, expression);
+	}
+	function walk(message) {
+		if (message instanceof ElementMessage && typeof message.identifier === "string") claim(tags, message.identifier, message.expression, `Duplicate element tag '${message.identifier}', give each element in a message its own tag unless they are identical`);
+		if ((message instanceof ArgumentMessage || message instanceof ChoiceMessage) && typeof message.identifier === "string") claim(values, message.identifier, message.expression, `Duplicate placeholder name '${message.identifier}', give each value in a message its own name unless they are identical`);
+		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) walk(branch.value);
+	}
+	walk(message);
+	for (const tag of tags.keys()) if (values.has(tag)) throw new Error(`Element tag '${tag}' collides with an argument of the same name`);
+	return /* @__PURE__ */ new Set([...tags.keys(), ...values.keys()]);
+}
+//#endregion
 //#region src/features/messages/convert.ts
 function convertMessageToIcu(message) {
 	function internalConvertMessageToIcu(message) {
 		switch (true) {
 			case message instanceof LiteralMessage: return String(message.text);
-			case message instanceof ArgumentMessage: return `{${String(message.identifier)}}`;
+			case message instanceof ArgumentMessage: {
+				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("");
@@ -129,11 +192,12 @@ function convertMessageToIcu(message) {
 			}
 			case message instanceof ChoiceMessage: {
 				const branches = message.branches.map(({ identifier, value }) => ({
-					identifier: Number.isNaN(+String(identifier)) ? String(identifier) : `=${+String(identifier)}`,
+					identifier: getBranchCase(message.kind, identifier),
 					value: internalConvertMessageToIcu(value)
 				})).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("");
 			default: throw new Error("Unknown message type", { cause: message });
@@ -142,4 +206,69 @@ function convertMessageToIcu(message) {
 	return internalConvertMessageToIcu(message).trim();
 }
 //#endregion
-export { AUTO_INCREMENT_IDENTIFIER, ArgumentMessage, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, assignSequenceIdentifiers, convertMessageToIcu, generateHash };
+//#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 { ARGUMENT_STYLES, ARGUMENT_TYPES, AUTO_INCREMENT_IDENTIFIER, ArgumentMessage, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, assignSequenceIdentifiers, convertMessageToIcu, 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.0",
+  "version": "0.7.0",
   "description": "CLI and configuration tooling for saykit",
   "keywords": [
     "cli",