eslint-soml 0.0.1

package/rules/no-unnormalized-keys.js

@@ -0,0 +1,62 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'no-unnormalized-keys';
+const messages = {
+	[MESSAGE_ID]: 'The key `{{key}}` is not in {{form}}, so it can look the same as a different key.',
+};
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	const [{form}] = context.options;
+
+	context.on('KeySegment', node => {
+		if (node.value.normalize(form) === node.value) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {
+				key: node.value,
+				form,
+			},
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow keys that are not in a Unicode normalization form.',
+			recommended: 'unopinionated',
+		},
+		schema: [
+			{
+				type: 'object',
+				additionalProperties: false,
+				properties: {
+					form: {
+						enum: ['NFC', 'NFD', 'NFKC', 'NFKD'],
+						description: 'The Unicode normalization form keys must be in.',
+					},
+				},
+			},
+		],
+		defaultOptions: [{form: 'NFC'}],
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/numeric-separators-style.js

@@ -0,0 +1,136 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'numeric-separators-style';
+const messages = {
+	[MESSAGE_ID]: 'Group the digits as `{{formatted}}`.',
+};
+
+const DECIMAL_NUMBER = /^(?<sign>-?)(?<integer>[\d_]+)(?:\.(?<fraction>[\d_]+))?(?:e(?<exponentSign>-?)(?<exponent>[\d_]+))?$/v;
+
+/*
+Groups `digits` with `_`, counting from the right, or from the left for a fraction. Fewer than `minimumDigits` digits, or no `groupLength`, means no grouping.
+*/
+function group(digits, {minimumDigits, groupLength, isFromLeft = false}) {
+	if (groupLength === undefined || digits.length < minimumDigits) {
+		return digits;
+	}
+
+	const groups = [];
+
+	if (isFromLeft) {
+		for (let start = 0; start < digits.length; start += groupLength) {
+			groups.push(digits.slice(start, start + groupLength));
+		}
+	} else {
+		for (let end = digits.length; end > 0; end -= groupLength) {
+			groups.unshift(digits.slice(Math.max(end - groupLength, 0), end));
+		}
+	}
+
+	return groups.join('_');
+}
+
+function format(text, options) {
+	const {sign, integer, fraction, exponentSign, exponent} = DECIMAL_NUMBER.exec(text).groups;
+	const strip = digits => digits.replaceAll('_', '');
+	let formatted = sign + group(strip(integer), options);
+
+	if (fraction !== undefined) {
+		formatted += `.${group(strip(fraction), {...options, groupLength: options.fractionGroupLength, isFromLeft: true})}`;
+	}
+
+	if (exponent !== undefined) {
+		formatted += `e${exponentSign}${group(strip(exponent), options)}`;
+	}
+
+	return formatted;
+}
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	const [options] = context.options;
+
+	context.on(['Integer', 'Float'], node => {
+		// A hexadecimal, octal, or binary int is grouped by what its digits mean, such as bytes or bits, so it is left alone.
+		if (node.type === 'Integer' ? node.radix !== 10 : !Number.isFinite(node.value)) {
+			return;
+		}
+
+		const text = context.sourceCode.getText(node);
+
+		if (options.onlyIfContainsSeparator && !text.includes('_')) {
+			return;
+		}
+
+		const formatted = format(text, options);
+
+		if (formatted === text) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {formatted},
+			fix: fixer => fixer.replaceText(node, formatted),
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce the grouping of digits with `_` in decimal numbers.',
+			recommended: true,
+		},
+		fixable: 'code',
+		schema: [
+			{
+				type: 'object',
+				additionalProperties: false,
+				properties: {
+					minimumDigits: {
+						type: 'integer',
+						minimum: 0,
+						description: 'The number of digits from which separators are required.',
+					},
+					groupLength: {
+						type: 'integer',
+						minimum: 1,
+						description: 'The number of digits in each group.',
+					},
+					fractionGroupLength: {
+						type: 'integer',
+						minimum: 1,
+						description: 'The number of digits in each group after the decimal point. By default, the digits after the decimal point are not grouped.',
+					},
+					onlyIfContainsSeparator: {
+						type: 'boolean',
+						description: 'Whether to only check numbers that already contain a separator.',
+					},
+				},
+			},
+		],
+		defaultOptions: [
+			{
+				minimumDigits: 5,
+				groupLength: 3,
+				onlyIfContainsSeparator: false,
+			},
+		],
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/prefer-bare-keys.js

@@ -0,0 +1,63 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'prefer-bare-keys';
+const messages = {
+	[MESSAGE_ID]: 'The key `{{key}}` does not need quotes.',
+};
+
+/*
+A bare key is ASCII letters, digits, `_`, and `-`.
+*/
+const BARE_KEY = /^[\w\-]+$/v;
+
+const isDigit = character => character >= '0' && character <= '9';
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('Key', function * (key) {
+		for (const [index, node] of key.segments.entries()) {
+			if (node.style === 'bare' || !BARE_KEY.test(node.value)) {
+				continue;
+			}
+
+			// Without quotes, a digit on both sides of a `.` reads as a number, as in `1.5`, which `no-numeric-dotted-keys` reports.
+			const previous = key.segments[index - 1]?.value ?? '';
+			const next = key.segments[index + 1]?.value ?? '';
+
+			if ((isDigit(previous.at(-1)) && isDigit(node.value[0])) || (isDigit(node.value.at(-1)) && isDigit(next[0]))) {
+				continue;
+			}
+
+			yield {
+				node,
+				messageId: MESSAGE_ID,
+				data: {key: node.value},
+				fix: fixer => fixer.replaceText(node, node.value),
+			};
+		}
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer bare keys when a key does not need quotes.',
+			recommended: true,
+		},
+		fixable: 'code',
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/prefer-literal-strings.js

@@ -0,0 +1,85 @@
+import {hasInvisibleCharacter} from './utils/index.js';
+
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+@import {StringNode, KeySegmentNode} from 'soml-lang';
+*/
+
+const MESSAGE_ID = 'prefer-literal-strings';
+const messages = {
+	[MESSAGE_ID]: 'Prefer a literal string. A `"…"` string is only needed for escapes.',
+};
+
+/*
+What a `'...'` string cannot hold: `'`, which would end it, and a line feed. A tab and every other control character stay escaped too, because they are invisible. That is also how canonical form decides.
+*/
+const NOT_LITERAL = /[\p{Control}']/v;
+
+/**
+The literal spelling of a string or key with the same value, or `undefined` when there is none.
+
+@param {StringNode | KeySegmentNode} node
+@param {string} text The source text of the node.
+@returns {string | undefined}
+*/
+function getLiteral(node, text) {
+	// A block string keeps its layout, so it only changes when its text already means the same without escapes. With no `'` in it, no line can close the new delimiter early.
+	if (node.block) {
+		if (text.includes('\\') || text.includes('\'') || hasInvisibleCharacter(text)) {
+			return;
+		}
+
+		const delimiter = '\''.repeat(text.indexOf('\n'));
+		return delimiter + text.slice(delimiter.length, -delimiter.length) + delimiter;
+	}
+
+	// Invisible characters stay escaped, as `no-invisible-characters` asks for.
+	if (NOT_LITERAL.test(node.value) || hasInvisibleCharacter(node.value)) {
+		return;
+	}
+
+	return `'${node.value}'`;
+}
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on(['String', 'KeySegment'], node => {
+		if (node.style !== 'escaped') {
+			return;
+		}
+
+		const literal = getLiteral(node, context.sourceCode.getText(node));
+
+		if (literal === undefined) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			fix: fixer => fixer.replaceText(node, literal),
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer literal strings, `\'…\'`, when a string has no escapes.',
+			recommended: true,
+		},
+		fixable: 'code',
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/prefer-utc-instants.js

@@ -0,0 +1,53 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'prefer-utc-instants';
+const messages = {
+	[MESSAGE_ID]: 'Write the instant in UTC, as `{{utc}}`.',
+};
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('Instant', node => {
+		const text = context.sourceCode.getText(node);
+
+		if (text.endsWith('Z')) {
+			return;
+		}
+
+		// Keep as many fractional digits as were written, so `.500` stays `.500`.
+		const fractionalSecondDigits = /\.(?<fraction>\d+)/v.exec(text)?.groups.fraction.length ?? 0;
+		const utc = node.value.toString({fractionalSecondDigits});
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {utc},
+			// The offset is not part of the value, so this keeps it.
+			fix: fixer => fixer.replaceText(node, utc),
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer instants in UTC.',
+			recommended: false,
+		},
+		fixable: 'code',
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/rule/index.js

@@ -0,0 +1,7 @@
+/**
+@import {SomlCreate} from './to-eslint-create.js';
+@import {SomlRule} from './to-eslint-rule.js';
+@import {SomlContext} from './soml-context.js';
+*/
+
+export {default as toEslintRules} from './to-eslint-rules.js';

package/rules/rule/soml-context.js

@@ -0,0 +1,47 @@
+/**
+@import {RuleContext} from '@eslint/core';
+@import {Node} from 'soml-lang';
+@import SomlListeners from './soml-listeners.js';
+@import {SomlProblems} from './to-eslint-problem.js';
+*/
+
+/**
+@typedef {RuleContext} SomlRuleContext
+*/
+
+/**
+@template {Node['type']} [NodeType=Node['type']]
+@typedef {(node: Extract<Node, {type: NodeType}>, parent: Node | undefined) => SomlProblems} SomlRuleListener
+*/
+
+/**
+@typedef {<NodeType extends Node['type']>(type: NodeType | NodeType[], listener: SomlRuleListener<NodeType>) => void} SomlRuleListen
+@typedef {SomlRuleContext & {
+	on: SomlRuleListen
+	onExit: SomlRuleListen
+}} SomlContext
+*/
+
+/**
+Create a better `Context` object with `on` and `onExit` method to add listeners
+
+@param {SomlRuleContext} eslintContext
+@param {SomlListeners} listeners
+@returns {SomlContext}
+*/
+export default function createSomlContext(eslintContext, listeners) {
+	/**
+	@type {SomlContext}
+	*/
+	const context = new Proxy(/** @type {SomlContext} */ (eslintContext), {
+		get(target, property, receiver) {
+			if (property === 'on' || property === 'onExit') {
+				return listeners[property].bind(listeners);
+			}
+
+			return Reflect.get(target, property, receiver);
+		},
+	});
+
+	return context;
+}

package/rules/rule/soml-listeners.js

@@ -0,0 +1,63 @@
+import toEslintListener from './to-eslint-listener.js';
+
+/**
+@import {RuleVisitor} from '@eslint/core';
+@import {Node} from 'soml-lang';
+@import {SomlRuleContext, SomlRuleListener} from './soml-context.js';
+*/
+
+export default class SomlListeners {
+	#context;
+	#listeners = new Map();
+
+	/**
+	@param {SomlRuleContext} context
+	*/
+	constructor(context) {
+		this.#context = context;
+	}
+
+	#addEventListener(selectors, listener) {
+		const listeners = this.#listeners;
+		for (const selector of selectors) {
+			if (listeners.has(selector)) {
+				listeners.get(selector).push(listener);
+			} else {
+				listeners.set(selector, [listener]);
+			}
+		}
+	}
+
+	/**
+	@template {Node['type']} NodeType
+	@param {NodeType | NodeType[]} selectorOrSelectors
+	@param {SomlRuleListener<NodeType>} listener
+	*/
+	on(selectorOrSelectors, listener) {
+		const selectors = Array.isArray(selectorOrSelectors) ? selectorOrSelectors : [selectorOrSelectors];
+		this.#addEventListener(selectors, listener);
+	}
+
+	/**
+	@template {Node['type']} NodeType
+	@param {NodeType | NodeType[]} selectorOrSelectors
+	@param {SomlRuleListener<NodeType>} listener
+	*/
+	onExit(selectorOrSelectors, listener) {
+		const selectors = Array.isArray(selectorOrSelectors) ? selectorOrSelectors : [selectorOrSelectors];
+		this.#addEventListener(selectors.map(selector => `${selector}:exit`), listener);
+	}
+
+	/**
+	@returns {RuleVisitor}
+	*/
+	toEslintListeners() {
+		const eslintListeners = {};
+
+		for (const [selector, listeners] of this.#listeners) {
+			eslintListeners[selector] = toEslintListener(this.#context, listeners);
+		}
+
+		return eslintListeners;
+	}
+}

package/rules/rule/to-eslint-create.js

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import createSomlContext from './soml-context.js';
+import SomlListeners from './soml-listeners.js';
+
+/**
+@import {RuleDefinition} from '@eslint/core';
+@import {SomlContext} from './soml-context.js';
+*/
+
+/**
+@typedef {RuleDefinition['create']} EslintCreate
+@typedef {(context: SomlContext) => void} SomlCreate
+*/
+
+/**
+Convert Soml style of `create` to ESLint style
+
+@param {SomlCreate} somlCreate
+@returns {EslintCreate}
+*/
+export default function toEslintCreate(somlCreate) {
+	return eslintContext => {
+		const somlListeners = new SomlListeners(eslintContext);
+		const somlContext = createSomlContext(eslintContext, somlListeners);
+
+		const result = somlCreate(somlContext);
+
+		assert.equal(result, undefined, `[${eslintContext.id}] Rule \`create\` function should return \`undefined\`, please use \`context.on()\` instead of return listeners.`);
+
+		const eslintListeners = somlListeners.toEslintListeners();
+
+		return eslintListeners;
+	};
+}

package/rules/rule/to-eslint-listener.js

@@ -0,0 +1,42 @@
+import {forEachFixOrProblem} from './utilities.js';
+import toEslintProblem from './to-eslint-problem.js';
+
+/**
+@import {RuleVisitor} from '@eslint/core';
+@import {Node} from 'soml-lang';
+@import {SomlRuleContext, SomlRuleListener} from './soml-context.js';
+*/
+
+/**
+@typedef {(node: Node, parent: Node | undefined) => void} EslintListener
+*/
+
+/**
+@param {SomlRuleContext} context
+@param {SomlRuleListener[]} listeners
+@returns {EslintListener}
+*/
+export default function toEslintListener(context, listeners) {
+	const reportProblem = somlProblem => {
+		if (somlProblem) {
+			context.report(toEslintProblem(somlProblem));
+		}
+	};
+
+	/*
+	Declared with fixed arity rather than rest arguments, since this runs for every node visit of every rule and a per-call rest array is measurable.
+	Listeners receive the node and its parent.
+	*/
+	return (node, parent) => {
+		for (const listener of listeners) {
+			const somlProblems = listener(node, parent);
+
+			// Listeners report nothing on the vast majority of nodes, so keep that path free of iterator allocation.
+			if (!somlProblems) {
+				continue;
+			}
+
+			forEachFixOrProblem(somlProblems, reportProblem);
+		}
+	};
+}

package/rules/rule/to-eslint-problem.js

@@ -0,0 +1,53 @@
+import toEslintFixer from './to-eslint-rule-fixer.js';
+
+/**
+@import {SomlRuleContext} from './soml-context.js';
+@import {SomlRuleFixer} from './to-eslint-rule-fixer.js';
+*/
+
+/**
+@typedef {Parameters<SomlRuleContext['report']>[0]} EslintProblem
+*/
+
+/**
+@template {NonNullable<EslintProblem['suggest']>[number]} [Suggestion=NonNullable<EslintProblem['suggest']>[number]]
+@typedef {Suggestion extends unknown ? Omit<Suggestion, 'fix'> & {fix: SomlRuleFixer} : never} SomlSuggestion
+*/
+
+/**
+@template {EslintProblem} [Problem=EslintProblem]
+@typedef {Problem extends unknown ? Omit<Problem, 'fix' | 'suggest'> & {fix?: SomlRuleFixer, suggest?: SomlSuggestion[]} : never} SomlProblem
+*/
+
+/**
+@typedef {SomlProblem | void | Iterable<SomlProblem | void>} SomlProblems
+*/
+
+/**
+@param {SomlProblem} somlProblem
+@returns {EslintProblem}
+*/
+export default function toEslintProblem(somlProblem) {
+	const {fix, suggest, ...problem} = somlProblem;
+	/**
+	@type {EslintProblem}
+	*/
+	const eslintProblem = problem;
+
+	if (fix) {
+		eslintProblem.fix = toEslintFixer(fix);
+	}
+
+	if (Array.isArray(suggest)) {
+		eslintProblem.suggest = suggest.map(somlSuggest => ({
+			...somlSuggest,
+			fix: toEslintFixer(somlSuggest.fix),
+			data: {
+				...somlProblem.data,
+				...somlSuggest.data,
+			},
+		}));
+	}
+
+	return eslintProblem;
+}