prettier-plugin-wolfram 0.7.0

package/src/rules/no-shadowed-pattern.js

@@ -0,0 +1,71 @@
+// src/rules/no-shadowed-pattern.js
+
+function collectModuleVars(node) {
+	const vars = new Set();
+	if (node.type !== "CallNode") return vars;
+	const headName = node.head?.value;
+	if (!["Module", "With", "Block", "DynamicModule"].includes(headName))
+		return vars;
+	const varList = node.children?.find((c) => c.type === "GroupNode");
+	if (!varList) return vars;
+	varList.children?.forEach((c) => {
+		if (c.type === "LeafNode" && c.kind === "Symbol") vars.add(c.value);
+		if (c.type === "BinaryNode" && c.op === "Set") {
+			const lhs = c.children?.[0];
+			if (lhs?.type === "LeafNode") vars.add(lhs.value);
+		}
+	});
+	return vars;
+}
+
+function findPatternVars(node) {
+	const vars = [];
+	walk(node, (n) => {
+		if (n.type === "CompoundNode" && n.op?.startsWith("Pattern")) {
+			const name = n.children?.find(
+				(c) => c.type === "LeafNode" && c.kind === "Symbol",
+			);
+			if (name) vars.push({ name: name.value, node: n });
+		}
+	});
+	return vars;
+}
+
+function walk(node, fn) {
+	if (!node) return;
+	fn(node);
+	node.children?.forEach((c) => walk(c, fn));
+	if (node.head) walk(node.head, fn);
+}
+
+export default {
+	name: "no-shadowed-pattern",
+	description: "Pattern variable shadows an outer Module/With/Block variable",
+	defaultLevel: "error",
+
+	visit(node, context) {
+		if (
+			node.type !== "BinaryNode" ||
+			!["Set", "SetDelayed"].includes(node.op)
+		)
+			return;
+
+		const rhs = node.children?.[node.children.length - 1];
+		if (!rhs) return;
+
+		const moduleVars = collectModuleVars(rhs);
+		if (moduleVars.size === 0) return;
+
+		const lhs = node.children?.[0];
+		const patVars = findPatternVars(lhs);
+
+		for (const { name, node: patNode } of patVars) {
+			if (moduleVars.has(name)) {
+				context.report({
+					node: patNode,
+					message: `Pattern variable "${name}" shadows a Module/With/Block local variable.`,
+				});
+			}
+		}
+	},
+};

package/src/rules/no-unused-module-var.js

@@ -0,0 +1,84 @@
+// src/rules/no-unused-module-var.js
+
+function getModuleVarNames(varListNode) {
+	const names = [];
+	if (!varListNode?.children) return names;
+	for (const child of varListNode.children) {
+		if (child.type === "LeafNode" && child.kind === "Symbol") {
+			names.push(child.value);
+		} else if (child.type === "BinaryNode" && child.op === "Set") {
+			const lhs = child.children?.[0];
+			if (lhs?.type === "LeafNode" && lhs.kind === "Symbol")
+				names.push(lhs.value);
+		}
+	}
+	return names;
+}
+
+function symbolsUsed(node, exclude = new Set()) {
+	const used = new Set();
+	walk(node, (n) => {
+		if (
+			n.type === "LeafNode" &&
+			n.kind === "Symbol" &&
+			!exclude.has(n.value)
+		) {
+			used.add(n.value);
+		}
+	});
+	return used;
+}
+
+function walk(node, fn) {
+	if (!node) return;
+	fn(node);
+	node.children?.forEach((c) => walk(c, fn));
+	if (node.head) walk(node.head, fn);
+}
+
+const BLOCK_OPS = new Set(["Module", "With", "Block", "DynamicModule"]);
+
+export default {
+	name: "no-unused-module-var",
+	description:
+		"Variables declared in Module/With/Block but never used in the body",
+	defaultLevel: "warn",
+
+	visit(node, context) {
+		if (node.type !== "CallNode") return;
+		const headName = node.head?.value;
+		if (!BLOCK_OPS.has(headName)) return;
+
+		const args =
+			node.children?.filter(
+				(c) =>
+					!(
+						c.type === "LeafNode" &&
+						[
+							"Token`Comma",
+							"Token`Whitespace",
+							"Token`Newline",
+						].includes(c.kind)
+					),
+			) ?? [];
+
+		if (args.length < 2) return;
+		const varList = args[0];
+		const body = args.slice(1);
+
+		const declared = getModuleVarNames(varList);
+		if (declared.length === 0) return;
+
+		const bodyUsed = new Set();
+		body.forEach((b) => symbolsUsed(b).forEach((s) => bodyUsed.add(s)));
+
+		for (const name of declared) {
+			if (!bodyUsed.has(name)) {
+				context.report({
+					node,
+					message: `Variable "${name}" declared in ${headName}[{...}] is never used in the body.`,
+				});
+			}
+		}
+	},
+};

package/src/rules/prefer-rule-delayed.js

@@ -0,0 +1,59 @@
+// src/rules/prefer-rule-delayed.js
+
+function collectPatternVars(node, vars = new Set()) {
+	if (!node) return vars;
+	if (
+		node.type === "CompoundNode" &&
+		(node.op === "PatternBlank" ||
+			node.op === "PatternBlankSequence" ||
+			node.op === "PatternBlankNullSequence" ||
+			node.op === "Pattern")
+	) {
+		const namePart = node.children?.find(
+			(c) => c.type === "LeafNode" && c.kind === "Symbol",
+		);
+		if (namePart) vars.add(namePart.value);
+	}
+	node.children?.forEach((c) => collectPatternVars(c, vars));
+	if (node.head) collectPatternVars(node.head, vars);
+	return vars;
+}
+
+function containsSymbol(node, names) {
+	if (!node) return false;
+	if (
+		node.type === "LeafNode" &&
+		node.kind === "Symbol" &&
+		names.has(node.value)
+	)
+		return true;
+	if (node.children?.some((c) => containsSymbol(c, names))) return true;
+	if (node.head && containsSymbol(node.head, names)) return true;
+	return false;
+}
+
+export default {
+	name: "prefer-rule-delayed",
+	description:
+		"f[x_] = body should be := when body references pattern variables",
+	defaultLevel: "warn",
+
+	visit(node, context) {
+		if (node.type !== "BinaryNode" || node.op !== "Set") return;
+		const [lhs, rhs] = [
+			node.children?.[0],
+			node.children?.[node.children.length - 1],
+		];
+		if (!lhs || !rhs) return;
+
+		const patVars = collectPatternVars(lhs);
+		if (patVars.size === 0) return;
+
+		if (containsSymbol(rhs, patVars)) {
+			context.report({
+				node,
+				message: `Use SetDelayed (:=) instead of Set (=) when the right-hand side references pattern variables (${[...patVars].join(", ")}).`,
+			});
+		}
+	},
+};

package/src/rules/spacing-commas.js

@@ -0,0 +1,64 @@
+// src/rules/spacing-commas.js
+
+function isWhitespace(node) {
+	return (
+		node?.type === "LeafNode" &&
+		["Token`Whitespace", "Whitespace"].includes(node.kind)
+	);
+}
+
+function isNewline(node) {
+	return (
+		node?.type === "LeafNode" &&
+		["Token`Newline", "Newline"].includes(node.kind)
+	);
+}
+
+function isComma(node) {
+	return node?.type === "LeafNode" && node.kind === "Token`Comma";
+}
+
+export default {
+	name: "spacing-commas",
+	description:
+		"Comma spacing inconsistent with wolfram.spaceAfterComma option",
+	defaultLevel: "warn",
+	fixableByFormatter: true,
+
+	visit(node, context) {
+		const children = node.children ?? [];
+		const wantSpaceAfter = context.options?.wolframSpaceAfterComma ?? true;
+
+		for (let i = 0; i < children.length; i++) {
+			const child = children[i];
+			if (!isComma(child)) continue;
+
+			const prev = children[i - 1];
+			const next = children[i + 1];
+
+			if (isWhitespace(prev)) {
+				context.report({
+					node: prev,
+					message: "Unexpected space before comma.",
+				});
+				return;
+			}
+
+			if (wantSpaceAfter) {
+				if (!isWhitespace(next) && !isNewline(next) && next) {
+					context.report({
+						node: child,
+						message: "Expected a space after comma.",
+					});
+					return;
+				}
+			} else if (isWhitespace(next)) {
+				context.report({
+					node: next,
+					message: "Unexpected space after comma.",
+				});
+				return;
+			}
+		}
+	},
+};

package/src/rules/spacing-operators.js

@@ -0,0 +1,87 @@
+// src/rules/spacing-operators.js
+
+import { wantsSpacesAroundOperator } from "../utils/operatorSpacing.js";
+
+function isDirectComment(child) {
+	return child?.type === "LeafNode" && child.kind === "Token`Comment";
+}
+
+export default {
+	name: "spacing-operators",
+	description:
+		"Operator spacing inconsistent with wolfram.spaceAroundOperators option",
+	defaultLevel: "warn",
+	fixableByFormatter: true,
+
+	visit(node, context) {
+		if (
+			node.type !== "InfixNode" &&
+			node.type !== "BinaryNode" &&
+			node.type !== "TernaryNode"
+		)
+			return;
+		const children = node.children ?? [];
+		if (children.some(isDirectComment)) return;
+
+		const isSpaceTrivia = (child) =>
+			child?.type === "LeafNode" &&
+			[
+				"Token`Whitespace",
+				"Whitespace",
+				"Token`Newline",
+				"Newline",
+			].includes(child.kind);
+		const ignoredOperatorKinds = new Set([
+			"Token`Comma",
+			"Token`Semi",
+			"Token`OpenSquare",
+			"Token`CloseSquare",
+			"Token`OpenParen",
+			"Token`CloseParen",
+			"Token`OpenCurly",
+			"Token`CloseCurly",
+			"Token`Amp",
+			"Token`Under",
+			"Token`UnderUnder",
+			"Token`UnderUnderUnder",
+			"Token`Blank",
+		]);
+
+		for (let i = 0; i < children.length; i++) {
+			const c = children[i];
+			if (c.type !== "LeafNode" || !c.kind.startsWith("Token`")) continue;
+			const isOp =
+				!ignoredOperatorKinds.has(c.kind) &&
+				![
+					"Token`Whitespace",
+					"Whitespace",
+					"Token`Newline",
+					"Newline",
+				].includes(c.kind) &&
+				!c.kind.startsWith("Token`Comment") &&
+				!c.kind.startsWith("Token`Fake`") &&
+				!c.kind.startsWith("Token`Hash");
+			if (!isOp) continue;
+			const wantSpaces = wantsSpacesAroundOperator(
+				node,
+				context.options,
+				c,
+			);
+			const prevIsWhitespace = i > 0 && isSpaceTrivia(children[i - 1]);
+			const nextIsWhitespace =
+				i < children.length - 1 && isSpaceTrivia(children[i + 1]);
+			const ok = wantSpaces
+				? prevIsWhitespace && nextIsWhitespace
+				: !prevIsWhitespace && !nextIsWhitespace;
+			if (!ok) {
+				context.report({
+					node: c,
+					message: wantSpaces
+						? `Expected spaces around operator "${c.value}".`
+						: `Expected no spaces around operator "${c.value}".`,
+				});
+				return;
+			}
+		}
+	},
+};

package/src/translator/commentSpacing.js

@@ -0,0 +1,51 @@
+import { doc } from "prettier";
+import { isComment } from "./nodes/leaf.js";
+import { sourceLineGap } from "./sourceLines.js";
+
+const { hardline } = doc.builders;
+
+function sourceTextBetween(leftNode, rightNode, options) {
+	if (
+		typeof options?.originalText !== "string" ||
+		typeof leftNode?.locEnd !== "number" ||
+		typeof rightNode?.locStart !== "number" ||
+		leftNode.locEnd > rightNode.locStart
+	) {
+		return null;
+	}
+
+	return options.originalText.slice(leftNode.locEnd, rightNode.locStart);
+}
+
+function sourceColumnsTouch(leftNode, rightNode) {
+	const leftEnd = leftNode?.source?.[1];
+	const rightStart = rightNode?.source?.[0];
+	if (!Array.isArray(leftEnd) || !Array.isArray(rightStart)) return false;
+	return leftEnd[0] === rightStart[0] && leftEnd[1] === rightStart[1];
+}
+
+function areTightAdjacentComments(leftNode, rightNode, options) {
+	if (!isComment(leftNode) || !isComment(rightNode)) return false;
+
+	const between = sourceTextBetween(leftNode, rightNode, options);
+	if (between != null) return between === "";
+
+	return sourceColumnsTouch(leftNode, rightNode);
+}
+
+export function sameLineCommentSeparator(leftNode, rightNode, options) {
+	return areTightAdjacentComments(leftNode, rightNode, options) ? "" : " ";
+}
+
+export function commentBoundarySeparator(
+	leftNode,
+	rightNode,
+	options,
+	fallback,
+) {
+	if (!rightNode) return "";
+	const gap = sourceLineGap(leftNode, rightNode, options);
+	if (gap === 0) return sameLineCommentSeparator(leftNode, rightNode, options);
+	if (gap > 0) return hardline;
+	return fallback;
+}

package/src/translator/docComments.js

@@ -0,0 +1,89 @@
+import { doc } from "prettier";
+import { normalizeWolframOptions } from "../options.js";
+import { sameLineCommentSeparator } from "./commentSpacing.js";
+
+export function joinDocsWithSpace(docs) {
+	const nonEmptyDocs = docs.filter(
+		(docNode) => docNode !== "" && docNode != null,
+	);
+	if (nonEmptyDocs.length === 0) return "";
+
+	const joined = [nonEmptyDocs[0]];
+	for (let i = 1; i < nonEmptyDocs.length; i++) {
+		joined.push(" ", nonEmptyDocs[i]);
+	}
+	return joined;
+}
+
+export function joinCommentDocs(comments, options) {
+	const nonEmptyComments = comments.filter(
+		(comment) => comment?.doc !== "" && comment?.doc != null,
+	);
+	if (nonEmptyComments.length === 0) return "";
+
+	const joined = [nonEmptyComments[0].doc];
+	for (let i = 1; i < nonEmptyComments.length; i++) {
+		joined.push(
+			sameLineCommentSeparator(
+				nonEmptyComments[i - 1].node,
+				nonEmptyComments[i].node,
+				options,
+			),
+			nonEmptyComments[i].doc,
+		);
+	}
+	return joined;
+}
+
+export function renderFlatDoc(docNode, options) {
+	const rendered = doc.printer.printDocToString(docNode, {
+		printWidth: 100000,
+		tabWidth: options.tabWidth ?? 2,
+		useTabs: false,
+		endOfLine: "lf",
+	}).formatted;
+	return rendered.endsWith("\n") ? rendered.slice(0, -1) : rendered;
+}
+
+export function documentationCommentColumn(
+	entries,
+	options,
+	suffixForEntry = () => "",
+) {
+	options = normalizeWolframOptions(options);
+	const manual = options.wolframDocumentationCommentColumn ?? 0;
+	if (manual > 0) return manual;
+	const padding = Math.max(
+		1,
+		options.wolframDocumentationCommentPadding ?? 2,
+	);
+
+	let maxCodeWidth = 0;
+	for (const entry of entries) {
+		if (!entry.trailingCommentDoc) continue;
+		const rendered = renderFlatDoc(
+			[entry.doc, suffixForEntry(entry)],
+			options,
+		);
+		if (rendered.includes("\n")) continue;
+		maxCodeWidth = Math.max(maxCodeWidth, rendered.length);
+	}
+	return maxCodeWidth + padding;
+}
+
+export function withAlignedTrailingComment(
+	entry,
+	options,
+	column,
+	suffix = "",
+) {
+	if (!entry.trailingCommentDoc) return [entry.doc, suffix];
+
+	const rendered = renderFlatDoc([entry.doc, suffix], options);
+	if (rendered.includes("\n")) {
+		return [entry.doc, suffix, " ", entry.trailingCommentDoc];
+	}
+
+	const gap = Math.max(1, column - rendered.length);
+	return [rendered, " ".repeat(gap), entry.trailingCommentDoc];
+}

package/src/translator/index.js

@@ -0,0 +1,98 @@
+// src/translator/index.js
+import { doc } from "prettier";
+import { printLeaf } from "./nodes/leaf.js";
+import { printContainer } from "./nodes/container.js";
+import { printCall } from "./nodes/call.js";
+import { printInfix } from "./nodes/infix.js";
+import { printBinary } from "./nodes/binary.js";
+import { printPrefix } from "./nodes/prefix.js";
+import { printPostfix } from "./nodes/postfix.js";
+import { printCompound } from "./nodes/compound.js";
+import { printGroup } from "./nodes/group.js";
+import { printTernary } from "./nodes/ternary.js";
+import { getSpecialPrinter } from "./specialForms.js";
+import { printOriginalSource } from "./sourcePreservation.js";
+
+const { hardline } = doc.builders;
+
+function withTrailingNewline(docNode, options) {
+	if (!options?.wolframTrailingNewline || docNode === "") return docNode;
+	return [docNode, hardline];
+}
+
+/**
+ * prettier's print function — called as path.call(print, ...) by prettier core.
+ * `path` is a FastPath; `path.getValue()` returns the current node.
+ */
+export function printNode(path, options, print) {
+	const node = path.getValue();
+	if (!node) return "";
+
+	switch (node.type) {
+		case "ContainerNode": {
+			const body = printContainer(node, options, (child) => {
+				return path.call(
+					print,
+					"children",
+					node.children.indexOf(child),
+				);
+			});
+			const fileDoc = node.wlsShebang
+				? body === ""
+					? node.wlsShebang
+					: [node.wlsShebang, hardline, body]
+				: body;
+			return withTrailingNewline(fileDoc, options);
+		}
+
+		case "LeafNode":
+			return printLeaf(node, options, { path });
+
+		case "CallNode": {
+			const special = getSpecialPrinter(node, options);
+			if (special) return special(path, options, print, node);
+			return printCall(path, options, print, node);
+		}
+
+		case "InfixNode": {
+			const special = getSpecialPrinter(node, options);
+			if (special) return special(path, options, print, node);
+			return printInfix(node, options, (child) =>
+				path.call(print, "children", node.children.indexOf(child)),
+			);
+		}
+
+		case "BinaryNode":
+			return printBinary(node, options, (child) =>
+				path.call(print, "children", node.children.indexOf(child)),
+			);
+
+		case "PrefixNode":
+			return printPrefix(node, options, (child) =>
+				path.call(print, "children", node.children.indexOf(child)),
+			);
+
+		case "PostfixNode":
+			return printPostfix(node, options, (child) =>
+				path.call(print, "children", node.children.indexOf(child)),
+			);
+
+		case "CompoundNode":
+			return printCompound(node, options, (child) =>
+				path.call(print, "children", node.children.indexOf(child)),
+			);
+
+		case "GroupNode":
+			return printGroup(path, options, print, node);
+
+		case "TernaryNode":
+			return printTernary(node, options, (child) =>
+				path.call(print, "children", node.children.indexOf(child)),
+			);
+
+		default:
+			// Unsupported CST nodes should round-trip the original source instead
+			// of exposing raw CodeParser internals in formatter output.
+			return printOriginalSource(node, options);
+	}
+}