@saykit/transform-js 0.9.0 → 0.10.0

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
@@ -9,10 +10,9 @@ declare function processExpression(expression: t.Node): [t.Expression, t.ObjectE
  * 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.
+ * An inline one-key object is the only shape this claims, and it could not mean
+ * anything else: interpolating an object stringifies it to `[object Object]`.
+ * Anything else is returned untouched.
  */
 declare function unwrapPlaceholder(expression: t.Expression): [string | typeof AUTO_INCREMENT_IDENTIFIER, t.Expression];
 /**
@@ -21,12 +21,25 @@ declare function unwrapPlaceholder(expression: t.Expression): [string | typeof A
  *
  * 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.
+ * name. An element is compared on its opening element alone, since its children
+ * come from the translation rather than the source.
  */
 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 above a
+ * message: `// TRANSLATORS: keep this under 20 characters`. A comment without
+ * 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.
+ *
+ * Babel attaches a comment on its own line to whatever node begins at it, 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,7 +10,7 @@ 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);
 }
 function buildTemplateChildren(template) {
 	return template.quasis.reduce((c, q, i) => {
@@ -28,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",
@@ -174,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.9.0",
+  "version": "0.10.0",
   "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.9.0"
+    "@saykit/config": "^0.10.0"
   },
   "devDependencies": {
     "@babel/core": "^7.29.7",