@saykit/config 0.7.0 → 0.8.0

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() {
@@ -135,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) {
@@ -177,10 +224,11 @@ 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 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);
@@ -188,23 +236,24 @@ function convertMessageToIcu(message) {
 			}
 			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(message.kind, identifier),
-					value: internalConvertMessageToIcu(value)
+					value: internalConvertMessageToIcu(value, scope)
 				})).map(({ identifier, value }) => `  ${identifier} {${value}}\n`).join("");
 				const format = message.kind === "ordinal" ? "selectordinal" : message.kind;
 				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
@@ -282,6 +331,7 @@ 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;

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

@@ -147,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 { ARGUMENT_STYLES, ARGUMENT_TYPES, AUTO_INCREMENT_IDENTIFIER, ArgumentFormat, ArgumentMessage, ArgumentType, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, Message, PlaceholderEquivalence, assignSequenceIdentifiers, convertMessageToIcu, generateHash, getBranchCase, isArgumentType, validateArgumentStyle, 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

@@ -147,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 { ARGUMENT_STYLES, ARGUMENT_TYPES, AUTO_INCREMENT_IDENTIFIER, ArgumentFormat, ArgumentMessage, ArgumentType, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, Message, PlaceholderEquivalence, assignSequenceIdentifiers, convertMessageToIcu, generateHash, getBranchCase, isArgumentType, validateArgumentStyle, 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() {
@@ -134,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) {
@@ -176,10 +223,11 @@ 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 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);
@@ -187,23 +235,24 @@ function convertMessageToIcu(message) {
 			}
 			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(message.kind, identifier),
-					value: internalConvertMessageToIcu(value)
+					value: internalConvertMessageToIcu(value, scope)
 				})).map(({ identifier, value }) => `  ${identifier} {${value}}\n`).join("");
 				const format = message.kind === "ordinal" ? "selectordinal" : message.kind;
 				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
@@ -271,4 +320,4 @@ function validateArgumentStyle(type, style) {
 	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 };
+export { ARGUMENT_STYLES, ARGUMENT_TYPES, AUTO_INCREMENT_IDENTIFIER, ArgumentMessage, ChoiceMessage, CompositeMessage, ElementMessage, LiteralMessage, assignSequenceIdentifiers, convertMessageToIcu, escapeIcuLiteral, generateHash, getBranchCase, isArgumentType, validateArgumentStyle, validateBranchIdentifier };

package/package.json

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