@saykit/transform-js 0.8.0 → 0.9.1

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { generateSayCallExpression } from "./generator.mjs";
-import { isEquivalentPlaceholder, parseExpression } from "./parser.mjs";
+import { collectLeadingComments, isEquivalentPlaceholder, parseExpression } from "./parser.mjs";
 import { generate } from "@babel/generator";
 import * as parser from "@babel/parser";
 import traverse_ from "@babel/traverse";
@@ -41,7 +41,7 @@ function createJsTransformer() {
 			const program = createProgram(code, id);
 			const messages = [];
 			traverse(program, { Expression(path) {
-				path.node.leadingComments = path.node.leadingComments ?? [];
+				path.node.leadingComments = collectLeadingComments(path);
 				const message = parseExpression(path.node);
 				if (message) {
 					assignSequenceIdentifiers(message, { current: 0 }, isEquivalentPlaceholder);
@@ -61,7 +61,6 @@ function createJsTransformer() {
 		transform(code, id) {
 			const program = createProgram(code, id);
 			traverse(program, { Expression(path) {
-				path.node.leadingComments = path.node.leadingComments ?? [];
 				const message = parseExpression(path.node);
 				if (message) {
 					assignSequenceIdentifiers(message, { current: 0 }, isEquivalentPlaceholder);

package/dist/parser.d.mts

@@ -1,3 +1,4 @@
+import { NodePath } from "@babel/traverse";
 import { AUTO_INCREMENT_IDENTIFIER, ArgumentMessage, CompositeMessage } from "@saykit/config/features/messages";
 import * as t from "@babel/types";
 //#region src/parser.d.ts
@@ -28,5 +29,21 @@ declare function unwrapPlaceholder(expression: t.Expression): [string | typeof A
 declare function isEquivalentPlaceholder(a: any, b: any): boolean;
 declare function parseExpression(expression: t.Expression, fallback?: false): CompositeMessage | null;
 declare function parseExpression(expression: t.Expression, fallback: true): CompositeMessage | ArgumentMessage;
+/**
+ * The notes a translator is meant to read, taken from the comments written
+ * above a message — `// TRANSLATORS: keep this under 20 characters`. A comment
+ * that does not open with the marker is a note to whoever is reading the code,
+ * and stays there.
+ */
+declare function getTranslatorComments(comments: readonly t.Comment[] | null | undefined): string[];
+/**
+ * The comments written in front of a message, in the order they were written.
+ *
+ * A comment on its own line is attached by Babel to whatever node happens to
+ * begin at it — `const a = say\`Hi\`` puts it on the declaration, not on the
+ * template — so a message is rarely the node holding its own notes. Walking out
+ * to the statement gathers them from wherever they landed.
+ */
+declare function collectLeadingComments(path: NodePath<t.Node>): t.Comment[];
 //#endregion
-export { isEquivalentPlaceholder, parseCallExpression, parseExpression, parseTaggedTemplateExpression, processExpression, unwrapPlaceholder };
+export { collectLeadingComments, getTranslatorComments, isEquivalentPlaceholder, parseCallExpression, parseExpression, parseTaggedTemplateExpression, processExpression, unwrapPlaceholder };

package/dist/parser.mjs

@@ -10,12 +10,8 @@ function parseTaggedTemplateExpression(tagged) {
 	return new CompositeMessage({
 		id: descriptor ? findPropertyValueIfStringLiteralAsString(descriptor, "id") : void 0,
 		context: descriptor ? findPropertyValueIfStringLiteralAsString(descriptor, "context") : void 0
-	}, getTranslatorComments(tagged.leadingComments ?? []), tagged.loc ? [`${tagged.loc.filename}:${tagged.loc.start.line}`] : [], children, accessor);
+	}, getTranslatorComments(tagged.leadingComments), tagged.loc ? [`${tagged.loc.filename}:${tagged.loc.start.line}`] : [], children, accessor);
 }
-/**
-* The text and the values of a template literal, in the order they were
-* written — the message the template spells out.
-*/
 function buildTemplateChildren(template) {
 	return template.quasis.reduce((c, q, i) => {
 		c.push(new LiteralMessage(q.value.cooked ?? q.value.raw));
@@ -32,7 +28,7 @@ function parseCallExpression(call) {
 	const wrap = (children) => new CompositeMessage({
 		id: descriptorId,
 		context: descriptorContext
-	}, [], call.loc ? [`${call.loc.filename}:${call.loc.start.line}`] : [], children, accessor);
+	}, getTranslatorComments(call.leadingComments), call.loc ? [`${call.loc.filename}:${call.loc.start.line}`] : [], children, accessor);
 	if (typeof kind === "string" && [
 		"select",
 		"ordinal",
@@ -77,15 +73,6 @@ function parseCallExpression(call) {
 	}
 	return null;
 }
-/**
-* The `offset` a plural subtracts from its selector before `#` is formatted, so
-* "You and 2 others" can select on a total of three.
-*
-* Read only from an integer literal: the offset is baked into the extracted
-* message, so it has to be known at build time, and a fractional or negative
-* one is not something ICU accepts. Anything else stays an ordinary branch and
-* is validated as the key it looks like.
-*/
 function findPluralOffset(object) {
 	for (const property of object.properties) {
 		if (!t.isObjectProperty(property) || property.computed) continue;
@@ -136,16 +123,6 @@ function getExpressionAsKey(node) {
 	if (t.isJSXIdentifier(node)) return node.name;
 	return AUTO_INCREMENT_IDENTIFIER;
 }
-/**
-* Read the name off a value written as a single-key object and hand back the
-* value alone, so the wrapper never reaches the output: `${{ total: sum() }}`
-* is `{total}` rather than `{0}`.
-*
-* An inline one-key object is the only shape this claims, and it is a shape
-* that could not mean anything else — interpolating an object stringifies it
-* to `[object Object]`, and rendering one in JSX throws. Anything else is
-* returned untouched and named the way it always was.
-*/
 function unwrapPlaceholder(expression) {
 	if (!t.isObjectExpression(expression) || expression.properties.length !== 1) return [getExpressionAsKey(expression), expression];
 	const [property] = expression.properties;
@@ -156,16 +133,6 @@ function unwrapPlaceholder(expression) {
 	if (!PLACEHOLDER_PATTERN.test(name)) throw new Error(`Invalid placeholder name '${name}', expected a letter or underscore followed by letters, digits, or underscores`);
 	return [name, property.value];
 }
-/**
-* Whether two placeholders sharing a name are the same placeholder, and so
-* compile to one prop a translator can move around the sentence freely.
-*
-* A value is compared whole: the same variable interpolated twice is one value,
-* while `${name}` beside `${{ name: author.name }}` is two things claiming one
-* name. An element is compared on its opening element alone — `say-tag` has
-* been stripped by the time this runs, and its children come from the
-* translation rather than the source.
-*/
 function isEquivalentPlaceholder(a, b) {
 	if (t.isJSXElement(a) || t.isJSXElement(b)) {
 		if (!t.isJSXElement(a) || !t.isJSXElement(b)) return false;
@@ -207,12 +174,43 @@ function findPropertyValueIfStringLiteralAsString(object, key) {
 		if (t.isIdentifier(property.key) && property.key.name === key && t.isStringLiteral(property.value)) return property.value.value;
 	}
 }
+const TRANSLATOR_COMMENT_PREFIX = "translators:";
 function getTranslatorComments(comments) {
-	return comments.reduce((a, c) => {
+	return (comments ?? []).reduce((a, c) => {
 		const text = c.value.trim();
-		if (text.toLowerCase().startsWith("translators:")) a.push(text.slice(12).trim());
+		if (text.toLowerCase().startsWith(TRANSLATOR_COMMENT_PREFIX)) a.push(text.slice(12).trim());
 		return a;
 	}, []);
 }
+function collectLeadingComments(path) {
+	const levels = [];
+	let current = path;
+	while (current) {
+		levels.push(current.node.leadingComments ?? []);
+		const parent = current.parentPath;
+		/* v8 ignore next */
+		if (!parent) break;
+		if (t.isJSXElement(parent.node) || t.isJSXFragment(parent.node)) {
+			levels.push(getPrecedingJSXComments(parent.node, current.node));
+			break;
+		}
+		if (t.isStatement(current.node) && !t.isExportDeclaration(parent.node)) break;
+		current = parent;
+	}
+	return [...new Set(levels.reverse().flat())];
+}
+function getPrecedingJSXComments(parent, node) {
+	const index = parent.children.indexOf(node);
+	/* v8 ignore next */
+	if (index === -1) return [];
+	const comments = [];
+	for (let i = index - 1; i >= 0; i--) {
+		const sibling = parent.children[i];
+		if (t.isJSXText(sibling) && !sibling.value.trim()) continue;
+		if (!t.isJSXExpressionContainer(sibling) || !t.isJSXEmptyExpression(sibling.expression)) break;
+		comments.unshift(...sibling.expression.innerComments ?? []);
+	}
+	return comments;
+}
 //#endregion
-export { isEquivalentPlaceholder, parseCallExpression, parseExpression, parseTaggedTemplateExpression, processExpression, unwrapPlaceholder };
+export { collectLeadingComments, getTranslatorComments, isEquivalentPlaceholder, parseCallExpression, parseExpression, parseTaggedTemplateExpression, processExpression, unwrapPlaceholder };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/transform-js",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "JavaScript and TypeScript transformer for SayKit",
   "keywords": [
     "i18n",
@@ -47,7 +47,7 @@
     "@babel/parser": "^7.29.7",
     "@babel/traverse": "^7.29.7",
     "@babel/types": "^7.29.7",
-    "@saykit/config": "^0.8.0"
+    "@saykit/config": "^0.9.1"
   },
   "devDependencies": {
     "@babel/core": "^7.29.7",