eslint-soml 0.0.1

package/rules/format.js

@@ -0,0 +1,134 @@
+import {format} from 'soml-lang';
+
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID_INSERT = 'format/insert';
+const MESSAGE_ID_DELETE = 'format/delete';
+const MESSAGE_ID_REPLACE = 'format/replace';
+const messages = {
+	[MESSAGE_ID_INSERT]: 'Insert `{{inserted}}`.',
+	[MESSAGE_ID_DELETE]: 'Delete `{{deleted}}`.',
+	[MESSAGE_ID_REPLACE]: 'Replace `{{deleted}}` with `{{inserted}}`.',
+};
+
+/*
+Shows whitespace in a message, the way eslint-plugin-prettier does.
+*/
+const showInvisibles = text => text
+	.replaceAll(' ', '·')
+	.replaceAll('\n', '⏎')
+	.replaceAll('\t', '↹');
+
+const GAP_CHARACTERS = new Set([' ', '\t', '\n', ',']);
+const isGapCharacter = character => GAP_CHARACTERS.has(character);
+
+/*
+The end of the run of spaces, tabs, line feeds, and commas at `index`.
+*/
+function skipGap(text, index) {
+	while (index < text.length && isGapCharacter(text[index])) {
+		index++;
+	}
+
+	return index;
+}
+
+/*
+The changes from `text` to `formatted`, as ranges of `text` and what replaces them.
+
+The formatter only changes spaces, tabs, line feeds, and commas, so without those the two texts are the same. Walking both at once, every run of those characters that differs is one change. This takes linear time, where a general diff takes quadratic time on a file with many changes.
+*/
+function * getChanges(text, formatted) {
+	let textIndex = 0;
+	let formattedIndex = 0;
+
+	while (textIndex < text.length || formattedIndex < formatted.length) {
+		const textGapEnd = skipGap(text, textIndex);
+		const formattedGapEnd = skipGap(formatted, formattedIndex);
+		const inserted = formatted.slice(formattedIndex, formattedGapEnd);
+
+		if (text.slice(textIndex, textGapEnd) !== inserted) {
+			yield {start: textIndex, end: textGapEnd, inserted};
+		}
+
+		textIndex = textGapEnd;
+		formattedIndex = formattedGapEnd;
+
+		while (textIndex < text.length && !isGapCharacter(text[textIndex]) && text[textIndex] === formatted[formattedIndex]) {
+			textIndex++;
+			formattedIndex++;
+		}
+
+		// Not expected, but if the formatter changed anything else, both stop at a different character, or one at its end, and the rest is one change.
+		const isTextStuck = textIndex === text.length || !isGapCharacter(text[textIndex]);
+		const isFormattedStuck = formattedIndex === formatted.length || !isGapCharacter(formatted[formattedIndex]);
+
+		if (isTextStuck && isFormattedStuck && (textIndex < text.length || formattedIndex < formatted.length)) {
+			yield {start: textIndex, end: text.length, inserted: formatted.slice(formattedIndex)};
+			return;
+		}
+	}
+}
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	const {sourceCode} = context;
+
+	context.on('Document', function * () {
+		const {text} = sourceCode;
+		const formatted = format(text);
+
+		if (formatted === text) {
+			return;
+		}
+
+		for (const {start, end, inserted} of getChanges(text, formatted)) {
+			const deleted = text.slice(start, end);
+			let messageId = MESSAGE_ID_REPLACE;
+
+			if (deleted === '') {
+				messageId = MESSAGE_ID_INSERT;
+			} else if (inserted === '') {
+				messageId = MESSAGE_ID_DELETE;
+			}
+
+			yield {
+				loc: {
+					start: sourceCode.getLocFromIndex(start),
+					end: sourceCode.getLocFromIndex(end),
+				},
+				messageId,
+				data: {
+					deleted: showInvisibles(deleted),
+					inserted: showInvisibles(inserted),
+				},
+				// The whole document is replaced, so the formatting is applied at once. Applying only some changes, when a fix from another rule overlaps one of them, could leave a comma or a block string half moved.
+				fix: fixer => fixer.replaceTextRange([0, text.length], formatted),
+			};
+		}
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'layout',
+		docs: {
+			description: 'Enforce the layout of the SOML formatter.',
+			recommended: true,
+		},
+		fixable: 'code',
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/index.js

@@ -0,0 +1,17 @@
+// Generated file, DO NOT edit
+
+export {default as format} from './format.js';
+export {default as 'key-name-casing'} from './key-name-casing.js';
+export {default as 'no-block-string-trailing-whitespace'} from './no-block-string-trailing-whitespace.js';
+export {default as 'no-empty-keys'} from './no-empty-keys.js';
+export {default as 'no-invisible-characters'} from './no-invisible-characters.js';
+export {default as 'no-loss-of-precision'} from './no-loss-of-precision.js';
+export {default as 'no-mixed-number-types'} from './no-mixed-number-types.js';
+export {default as 'no-numeric-dotted-keys'} from './no-numeric-dotted-keys.js';
+export {default as 'no-unnormalized-keys'} from './no-unnormalized-keys.js';
+export {default as 'numeric-separators-style'} from './numeric-separators-style.js';
+export {default as 'prefer-bare-keys'} from './prefer-bare-keys.js';
+export {default as 'prefer-literal-strings'} from './prefer-literal-strings.js';
+export {default as 'prefer-utc-instants'} from './prefer-utc-instants.js';
+export {default as 'sort-keys'} from './sort-keys.js';
+export {default as 'spaced-comment'} from './spaced-comment.js';

package/rules/key-name-casing.js

@@ -0,0 +1,94 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'key-name-casing';
+const messages = {
+	[MESSAGE_ID]: 'The key `{{key}}` is not in {{case}}.',
+};
+
+/*
+Digits are allowed anywhere, so `http2-port` is kebab-case, and `404` passes in every case.
+*/
+const CASES = {
+	'kebab-case': /^[\da-z]+(?:-[\da-z]+)*$/v,
+	camelCase: /^[\da-z][\dA-Za-z]*$/v,
+	// eslint-disable-next-line camelcase -- The name of the case is the option value.
+	snake_case: /^[\da-z]+(?:_[\da-z]+)*$/v,
+	PascalCase: /^[\dA-Z][\dA-Za-z]*$/v,
+};
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	const [{case: keyCase, ignore}] = context.options;
+	const pattern = CASES[keyCase];
+	// The `u` flag, as in ESLint's own rules, because the `v` flag rejects some escapes that people write, such as `\-`.
+	const ignorePatterns = ignore.map(source => new RegExp(source, 'u'));
+
+	context.on('KeySegment', node => {
+		// A quoted key holds data rather than a name, such as a path or a URL, so it is not checked.
+		if (
+			node.style !== 'bare'
+			|| pattern.test(node.value)
+			|| ignorePatterns.some(ignorePattern => ignorePattern.test(node.value))
+		) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {
+				key: node.value,
+				case: keyCase,
+			},
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a casing style for keys.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				additionalProperties: false,
+				properties: {
+					case: {
+						enum: Object.keys(CASES),
+						description: 'The casing style keys must use.',
+					},
+					ignore: {
+						type: 'array',
+						uniqueItems: true,
+						items: {
+							type: 'string',
+						},
+						description: 'Regular expressions for keys to ignore.',
+					},
+				},
+			},
+		],
+		defaultOptions: [
+			{
+				case: 'kebab-case',
+				ignore: [],
+			},
+		],
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/no-block-string-trailing-whitespace.js

@@ -0,0 +1,64 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'no-block-string-trailing-whitespace';
+const messages = {
+	[MESSAGE_ID]: 'Whitespace at the end of a line in a block string is part of the value, and editors often remove it.',
+};
+
+const TRAILING_WHITESPACE = /[\t ]+$/v;
+const BLANK_LINE = /^[\t ]*$/v;
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	const {sourceCode} = context;
+
+	context.on('String', function * (node) {
+		if (!node.block) {
+			return;
+		}
+
+		const lines = sourceCode.getText(node).split('\n');
+		let offset = sourceCode.getRange(node)[0] + lines[0].length + 1;
+
+		// The first line holds the opening delimiter, and the last line the closing one.
+		for (const line of lines.slice(1, -1)) {
+			const match = TRAILING_WHITESPACE.exec(line);
+
+			// A blank line becomes an empty line, so its whitespace is not part of the value.
+			if (match && !BLANK_LINE.test(line)) {
+				yield {
+					loc: {
+						start: sourceCode.getLocFromIndex(offset + match.index),
+						end: sourceCode.getLocFromIndex(offset + line.length),
+					},
+					messageId: MESSAGE_ID,
+				};
+			}
+
+			offset += line.length + 1;
+		}
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow trailing whitespace in block strings.',
+			recommended: 'unopinionated',
+		},
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/no-empty-keys.js

@@ -0,0 +1,43 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'no-empty-keys';
+const messages = {
+	[MESSAGE_ID]: 'Empty keys are not allowed.',
+};
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('KeySegment', node => {
+		if (node.value !== '') {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow empty keys.',
+			recommended: 'unopinionated',
+		},
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/no-invisible-characters.js

@@ -0,0 +1,90 @@
+import {matchInvisibleCharacters, toUnicodeEscape, toEscapedString} from './utils/index.js';
+
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+@import {StringNode, KeySegmentNode, Comment} from 'soml-lang';
+*/
+
+const MESSAGE_ID = 'no-invisible-characters';
+const messages = {
+	[MESSAGE_ID]: 'The character U+{{codePoint}} is invisible or looks like a space. Write it as an escape, `{{escape}}`.',
+};
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	const {sourceCode} = context;
+
+	/**
+	@param {StringNode | KeySegmentNode | Comment} node
+	@param {((fixer: any, character: string, start: number) => any) | undefined} fix
+	*/
+	function * getProblems(node, fix) {
+		const text = sourceCode.getText(node);
+
+		for (const match of matchInvisibleCharacters(text)) {
+			const [character] = match;
+			const start = sourceCode.getRange(node)[0] + match.index;
+			const end = start + character.length;
+
+			yield {
+				loc: {
+					start: sourceCode.getLocFromIndex(start),
+					end: sourceCode.getLocFromIndex(end),
+				},
+				messageId: MESSAGE_ID,
+				data: {
+					codePoint: character.codePointAt(0).toString(16).toUpperCase().padStart(4, '0'),
+					escape: toUnicodeEscape(character),
+				},
+				fix: fix && (fixer => fix(fixer, character, start)),
+			};
+		}
+	}
+
+	/**
+	@param {StringNode | KeySegmentNode} node
+	*/
+	function getFix(node) {
+		// In `"..."`, the character can be replaced by its escape where it is.
+		if (node.style === 'escaped') {
+			return (fixer, character, start) => fixer.replaceTextRange([start, start + character.length], toUnicodeEscape(character));
+		}
+
+		// A `'...'` string has no escapes, so it becomes a `"..."` string. A `'''` block would need its content re-escaped line by line, so it is left to the author.
+		if (node.style === 'literal' && !node.block) {
+			return fixer => fixer.replaceText(node, toEscapedString(node.value));
+		}
+	}
+
+	context.on(['String', 'KeySegment'], node => {
+		if (node.style === 'bare') {
+			return;
+		}
+
+		return getProblems(node, getFix(node));
+	});
+
+	context.on('Document', () => sourceCode.getAllComments().map(comment => getProblems(comment)));
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow invisible characters in strings, keys, and comments.',
+			recommended: 'unopinionated',
+		},
+		fixable: 'code',
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/no-loss-of-precision.js

@@ -0,0 +1,96 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'no-loss-of-precision';
+const messages = {
+	[MESSAGE_ID]: 'This number cannot be stored exactly as a float. Its value is `{{value}}`.',
+};
+
+/*
+The significant digits and the exponent of a decimal number, without leading or trailing zeros. `0.0150` is the digits `15` and the exponent `-2`, which is 1.5e-2.
+*/
+function normalize(text) {
+	const [mantissa, exponent = '0'] = text.replaceAll('_', '').replace(/^-/v, '').split('e', 2);
+	const [integer, fraction = ''] = mantissa.split('.', 2);
+	const allDigits = integer + fraction;
+	const significant = allDigits.replace(/^0+/v, '');
+	const leadingZeros = allDigits.length - significant.length;
+
+	return {
+		digits: significant.replace(/0+$/v, ''),
+		exponent: Number(exponent) + integer.length - 1 - leadingZeros,
+	};
+}
+
+/*
+Whether the stored float, written with as many significant digits as the literal has, is not the literal. This is how ESLint's own `no-loss-of-precision` rule decides.
+*/
+function losesPrecision(text, value) {
+	const literal = normalize(text);
+
+	// Zero is exact.
+	if (literal.digits === '') {
+		return false;
+	}
+
+	// `toExponential()` takes at most 100 fraction digits. A float written exactly with more digits than that, which is rare, is reported anyway.
+	if (literal.digits.length > 101) {
+		return true;
+	}
+
+	const stored = normalize(Math.abs(value).toExponential(literal.digits.length - 1));
+	return stored.digits !== literal.digits || stored.exponent !== literal.exponent;
+}
+
+/*
+A float as canonical form writes it: JavaScript's spelling, with `.0` added so it does not read as an int, and no `+` in the exponent.
+*/
+function formatFloat(value) {
+	const text = String(value).replace('e+', 'e');
+	return /[.e]/v.test(text) ? text : `${text}.0`;
+}
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('Float', node => {
+		if (!Number.isFinite(node.value)) {
+			return;
+		}
+
+		const text = context.sourceCode.getText(node);
+
+		if (!losesPrecision(text, node.value)) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {
+				value: formatFloat(node.value),
+			},
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow floats that cannot be stored exactly as written.',
+			recommended: 'unopinionated',
+		},
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/no-mixed-number-types.js

@@ -0,0 +1,81 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID_INT = 'no-mixed-number-types/int';
+const MESSAGE_ID_FLOAT = 'no-mixed-number-types/float';
+const MESSAGE_ID_SUGGESTION = 'no-mixed-number-types/suggestion';
+const messages = {
+	[MESSAGE_ID_INT]: '`{{number}}` is an int, but the other numbers in this array are floats.',
+	[MESSAGE_ID_FLOAT]: '`{{number}}` is a float, but the other numbers in this array are ints.',
+	[MESSAGE_ID_SUGGESTION]: 'Write it as a float: `{{replacement}}`.',
+};
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	const {sourceCode} = context;
+
+	context.on('Array', function * (node) {
+		const ints = node.elements.filter(element => element.type === 'Integer');
+		const floats = node.elements.filter(element => element.type === 'Float');
+
+		if (ints.length === 0 || floats.length === 0) {
+			return;
+		}
+
+		// The fewer kind is the likely mistake. An int becomes a float by adding `.0`, which only works for a decimal int.
+		if (ints.length <= floats.length) {
+			for (const int of ints) {
+				const number = sourceCode.getText(int);
+				const replacement = `${number}.0`;
+
+				yield {
+					node: int,
+					messageId: MESSAGE_ID_INT,
+					data: {number},
+					...(int.radix === 10 && {
+						suggest: [
+							{
+								messageId: MESSAGE_ID_SUGGESTION,
+								data: {replacement},
+								fix: fixer => fixer.replaceText(int, replacement),
+							},
+						],
+					}),
+				};
+			}
+
+			return;
+		}
+
+		for (const float of floats) {
+			yield {
+				node: float,
+				messageId: MESSAGE_ID_FLOAT,
+				data: {number: sourceCode.getText(float)},
+			};
+		}
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow arrays that mix ints and floats.',
+			recommended: true,
+		},
+		hasSuggestions: true,
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/no-numeric-dotted-keys.js

@@ -0,0 +1,81 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+@import {KeySegmentNode} from 'soml-lang';
+*/
+
+const MESSAGE_ID_ERROR = 'no-numeric-dotted-keys/error';
+const MESSAGE_ID_SUGGESTION = 'no-numeric-dotted-keys/suggestion';
+const messages = {
+	[MESSAGE_ID_ERROR]: '`{{key}}` is a nested key, because `.` separates key segments. It is not one key.',
+	[MESSAGE_ID_SUGGESTION]: 'Quote it as one key: `{{replacement}}`.',
+};
+
+const isDigit = character => character >= '0' && character <= '9';
+
+/**
+Whether the `.` between two segments reads as a decimal point, as in `3.14` or `python3.12`.
+
+@param {KeySegmentNode} segment
+@param {KeySegmentNode} next
+*/
+const isDecimalPoint = (segment, next) =>
+	segment.style === 'bare'
+	&& next.style === 'bare'
+	&& isDigit(segment.value.at(-1))
+	&& isDigit(next.value[0]);
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('Key', node => {
+		const {segments} = node;
+
+		const hasDecimalPoint = segments.slice(1).some((next, index) => isDecimalPoint(segments[index], next));
+
+		if (!hasDecimalPoint) {
+			return;
+		}
+
+		const key = context.sourceCode.getText(node);
+		const problem = {
+			node,
+			messageId: MESSAGE_ID_ERROR,
+			data: {key},
+		};
+
+		// A key with quoted segments has no single obvious meaning, so it gets no suggestion. Bare segments never contain `'`.
+		if (segments.every(segment => segment.style === 'bare')) {
+			const replacement = `'${key}'`;
+			problem.suggest = [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					data: {replacement},
+					fix: fixer => fixer.replaceText(node, replacement),
+				},
+			];
+		}
+
+		return problem;
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow dotted keys that read as one number.',
+			recommended: 'unopinionated',
+		},
+		hasSuggestions: true,
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;