eslint-soml 0.0.1

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

@@ -0,0 +1,56 @@
+import {forEachFixOrProblem} from './utilities.js';
+
+/**
+@import {RuleTextEditor} from '@eslint/core';
+@import {Node} from 'soml-lang';
+@import {EslintProblem} from './to-eslint-problem.js';
+*/
+
+class FixAbortError extends Error {
+	name = 'FixAbortError';
+}
+
+const fixOptions = {
+	abort() {
+		throw new FixAbortError('Fix aborted.');
+	},
+};
+
+/**
+@typedef {NonNullable<EslintProblem['fix']>} EslintRuleFixer
+@typedef {RuleTextEditor<Node>} SomlFixer
+@typedef {ReturnType<SomlFixer['replaceText']> | void} EslintReportFixer
+@typedef {EslintReportFixer | Iterable<EslintReportFixer>} SomlReportFixer
+@typedef {(fixer: SomlFixer, options: typeof fixOptions) => SomlReportFixer} SomlRuleFixer
+*/
+
+/**
+Convert Soml style fix function to ESLint style fix function
+
+@param {SomlRuleFixer} fix
+@returns {EslintRuleFixer}
+*/
+export default function toEslintRuleFixer(fix) {
+	/**
+	@param {SomlFixer} fixer
+	*/
+	return fixer => {
+		const eslintReport = [];
+
+		try {
+			const somlReport = fix(fixer, fixOptions);
+			forEachFixOrProblem(somlReport, eslintFix => {
+				eslintReport.push(eslintFix);
+			});
+
+			return eslintReport;
+		} catch (error) {
+			if (error instanceof FixAbortError) {
+				return [];
+			}
+
+			/* c8 ignore next */
+			throw error;
+		}
+	};
+}

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

@@ -0,0 +1,36 @@
+import getDocumentationUrl from '../utils/get-documentation-url.js';
+import toEslintCreate from './to-eslint-create.js';
+
+/**
+@import {RuleDefinition} from '@eslint/core';
+@import {SomlCreate} from './to-eslint-create.js';
+*/
+
+/**
+@typedef {Omit<RuleDefinition, 'create'> & {
+	create: SomlCreate
+}} SomlRule
+*/
+
+/**
+Convert Soml rule to ESLint rule
+
+@param {string} ruleId
+@param {SomlRule} somlRule
+@returns {RuleDefinition}
+*/
+export default function toEslintRule(ruleId, somlRule) {
+	return {
+		meta: {
+			// If there are no options, add `[]` so ESLint can validate that no data is passed to the rule.
+			// https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-schema.md
+			schema: [],
+			...somlRule.meta,
+			docs: {
+				...somlRule.meta.docs,
+				url: getDocumentationUrl(ruleId),
+			},
+		},
+		create: toEslintCreate(somlRule.create),
+	};
+}

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

@@ -0,0 +1,9 @@
+import toEslintRule from './to-eslint-rule.js';
+
+export default function toEslintRules(rules) {
+	return Object.fromEntries(Object.entries(rules).map(([ruleId, rule]) => [
+		ruleId,
+		toEslintRule(ruleId, rule),
+	]));
+}
+

package/rules/rule/utilities.js

@@ -0,0 +1,29 @@
+const isIterable = object => typeof object?.[Symbol.iterator] === 'function';
+
+/**
+@import * as ESLint from 'eslint';
+@import {SomlReportFixer} from './to-eslint-rule-fixer.js';
+@import {SomlProblems, SomlProblem} from './to-eslint-problem.js';
+*/
+
+/**
+Call `callback` for each ESLint fix or ESLint problem in `value`, flattening nested iterables.
+
+This runs for every listener call of every rule, so it deliberately avoids generators and intermediate arrays.
+
+@template {SomlReportFixer | SomlProblems} ValueType
+
+@param {ValueType} value
+@param {(value: ValueType extends SomlReportFixer ? ESLint.Rule.Fix : SomlProblem) => void} callback
+@returns {void}
+*/
+export function forEachFixOrProblem(value, callback) {
+	if (!isIterable(value)) {
+		callback(value);
+		return;
+	}
+
+	for (const element of value) {
+		forEachFixOrProblem(element, callback);
+	}
+}

package/rules/sort-keys.js

@@ -0,0 +1,187 @@
+import naturalCompare from 'natural-compare';
+
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+@import {MemberNode} from 'soml-lang';
+*/
+
+const MESSAGE_ID = 'sort-keys';
+const messages = {
+	[MESSAGE_ID]: 'Expected keys to be in {{sortName}} case-{{sensitivity}} {{direction}} order. `{{thisName}}` should be before `{{previousName}}`.',
+};
+
+const compareAlphanumeric = (first, second) => {
+	if (first === second) {
+		return 0;
+	}
+
+	return first < second ? -1 : 1;
+};
+
+/*
+The decoded key path, so `'a'` and `a` sort the same.
+*/
+const getName = member => member.key.segments.map(segment => segment.value).join('.');
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	const {sourceCode} = context;
+	const [direction, {caseSensitive, natural, minKeys, allowLineSeparatedGroups}] = context.options;
+	const compare = natural ? naturalCompare : compareAlphanumeric;
+	const normalize = caseSensitive ? name => name : name => name.toLowerCase();
+	const sign = direction === 'asc' ? 1 : -1;
+	const isInOrder = (previous, next) => sign * compare(normalize(previous), normalize(next)) <= 0;
+
+	/**
+	Whether a blank line separates two members. A line that holds a comment is not blank.
+
+	@param {MemberNode} previous
+	@param {MemberNode} member
+	*/
+	function isLineSeparated(previous, member) {
+		const lines = sourceCode.lines.slice(sourceCode.getLoc(previous).end.line, sourceCode.getLoc(member).start.line - 1);
+		const commentLines = new Set(sourceCode.getAllComments().flatMap(comment => {
+			const {start, end} = sourceCode.getLoc(comment);
+			return Array.from({length: end.line - start.line + 1}, (_, index) => start.line + index);
+		}));
+
+		return lines.some((line, index) => line.trim() === '' && !commentLines.has(sourceCode.getLoc(previous).end.line + index + 1));
+	}
+
+	/**
+	Whether a comment is directly before or after a member, so that swapping members would move it to the wrong one.
+
+	@param {MemberNode} member
+	*/
+	function hasAdjacentComment(member) {
+		const isComment = token => token?.type === 'Line' || token?.type === 'Block';
+		let after = sourceCode.getTokenAfter(member, {includeComments: true});
+
+		if (after?.value === ',') {
+			after = sourceCode.getTokenAfter(after, {includeComments: true});
+		}
+
+		return isComment(sourceCode.getTokenBefore(member, {includeComments: true})) || isComment(after);
+	}
+
+	context.on('Object', function * (node) {
+		if (node.members.length < minKeys) {
+			return;
+		}
+
+		// A blank line starts a group that is sorted on its own, when that is allowed.
+		const groups = [];
+
+		for (const [index, member] of node.members.entries()) {
+			const previous = node.members[index - 1];
+
+			if (previous === undefined || (allowLineSeparatedGroups && isLineSeparated(previous, member))) {
+				groups.push([]);
+			}
+
+			groups.at(-1).push(member);
+		}
+
+		/*
+		Sorts the whole object at once, by putting each member's text where it belongs, so one run of `--fix` is enough. Object members have no order in SOML, so this keeps the value.
+		*/
+		function * fix(fixer, {abort}) {
+			if (node.members.some(member => hasAdjacentComment(member))) {
+				abort();
+			}
+
+			for (const group of groups) {
+				const sorted = group.toSorted((first, second) => sign * compare(normalize(getName(first)), normalize(getName(second))));
+
+				for (const [index, member] of group.entries()) {
+					if (sorted[index] !== member) {
+						yield fixer.replaceText(member, sourceCode.getText(sorted[index]));
+					}
+				}
+			}
+		}
+
+		for (const group of groups) {
+			for (const [index, member] of group.entries()) {
+				const previous = group[index - 1];
+
+				if (previous === undefined || isInOrder(getName(previous), getName(member))) {
+					continue;
+				}
+
+				yield {
+					node: member.key,
+					messageId: MESSAGE_ID,
+					data: {
+						thisName: sourceCode.getText(member.key),
+						previousName: sourceCode.getText(previous.key),
+						direction: direction === 'asc' ? 'ascending' : 'descending',
+						sensitivity: caseSensitive ? 'sensitive' : 'insensitive',
+						sortName: natural ? 'natural' : 'alphanumeric',
+					},
+					fix,
+				};
+			}
+		}
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Require object keys to be sorted.',
+			recommended: false,
+		},
+		fixable: 'code',
+		schema: [
+			{
+				enum: ['asc', 'desc'],
+				description: 'The sort direction.',
+			},
+			{
+				type: 'object',
+				additionalProperties: false,
+				properties: {
+					caseSensitive: {
+						type: 'boolean',
+						description: 'Whether uppercase and lowercase letters are sorted apart.',
+					},
+					natural: {
+						type: 'boolean',
+						description: 'Whether numbers in keys are sorted by their value, so `a2` comes before `a10`.',
+					},
+					minKeys: {
+						type: 'integer',
+						minimum: 2,
+						description: 'The number of keys from which an object must be sorted.',
+					},
+					allowLineSeparatedGroups: {
+						type: 'boolean',
+						description: 'Whether a blank line starts a new group that is sorted on its own.',
+					},
+				},
+			},
+		],
+		defaultOptions: [
+			'asc',
+			{
+				caseSensitive: true,
+				natural: false,
+				minKeys: 2,
+				allowLineSeparatedGroups: false,
+			},
+		],
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/spaced-comment.js

@@ -0,0 +1,83 @@
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID_START = 'spaced-comment/start';
+const MESSAGE_ID_END = 'spaced-comment/end';
+const messages = {
+	[MESSAGE_ID_START]: 'Add a space after `{{marker}}`.',
+	[MESSAGE_ID_END]: 'Add a space before `*/`.',
+};
+
+/*
+A line comment may start with more `#`, as in `## Section`. A block comment may start or end with more `*`, as in a banner.
+*/
+const LINE_START = /^[\s#]/v;
+const BLOCK_START = /^[\s*]/v;
+const BLOCK_END = /[\s*]$/v;
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('Document', function * () {
+		for (const comment of context.sourceCode.getAllComments()) {
+			const {value} = comment;
+			const [start, end] = context.sourceCode.getRange(comment);
+
+			if (value === '') {
+				continue;
+			}
+
+			if (comment.type === 'Line') {
+				if (!LINE_START.test(value)) {
+					yield {
+						node: comment,
+						messageId: MESSAGE_ID_START,
+						data: {marker: '#'},
+						fix: fixer => fixer.insertTextAfterRange([start, start + 1], ' '),
+					};
+				}
+
+				continue;
+			}
+
+			if (!BLOCK_START.test(value)) {
+				yield {
+					node: comment,
+					messageId: MESSAGE_ID_START,
+					data: {marker: '/*'},
+					fix: fixer => fixer.insertTextAfterRange([start, start + 2], ' '),
+				};
+			}
+
+			if (!BLOCK_END.test(value)) {
+				yield {
+					node: comment,
+					messageId: MESSAGE_ID_END,
+					fix: fixer => fixer.insertTextBeforeRange([end - 2, end], ' '),
+				};
+			}
+		}
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'layout',
+		docs: {
+			description: 'Require a space after `#` and `/*`, and before `*/`.',
+			recommended: true,
+		},
+		fixable: 'whitespace',
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/utils/escape-string.js

@@ -0,0 +1,30 @@
+import {invisibleCharacterPattern} from './invisible-characters.js';
+
+const invisibleCharacters = new RegExp(invisibleCharacterPattern, 'gv');
+
+/**
+Write a character as a `\u{…}` escape, in the one spelling SOML allows: lowercase hex digits and no leading zero.
+
+@param {string} character
+@returns {string}
+*/
+export function toUnicodeEscape(character) {
+	return String.raw`\u{${character.codePointAt(0).toString(16)}}`;
+}
+
+/**
+Write `value` as a `"..."` string. `\`, `"`, LF, and tab use their short escapes, and every invisible character uses a `\u{…}` escape.
+
+@param {string} value
+@returns {string}
+*/
+export function toEscapedString(value) {
+	const escaped = value
+		.replaceAll('\\', '\\\\')
+		.replaceAll('"', String.raw`\"`)
+		.replaceAll('\n', String.raw`\n`)
+		.replaceAll('\t', String.raw`\t`)
+		.replaceAll(invisibleCharacters, character => toUnicodeEscape(character));
+
+	return `"${escaped}"`;
+}

package/rules/utils/get-documentation-url.js

@@ -0,0 +1,15 @@
+import path from 'node:path';
+import packageJson from '../../package.json' with {type: 'json'};
+
+const repositoryUrl = 'https://github.com/sindresorhus/eslint-soml';
+
+/**
+The URL of a rule's documentation, for the version of this package.
+
+@param {string} filename The rule's file name or path.
+@returns {string}
+*/
+export default function getDocumentationUrl(filename) {
+	const ruleName = path.basename(filename, '.js');
+	return `${repositoryUrl}/blob/v${packageJson.version}/docs/rules/${ruleName}.md`;
+}

package/rules/utils/index.js

@@ -0,0 +1,2 @@
+export {invisibleCharacterPattern, matchInvisibleCharacters, hasInvisibleCharacter} from './invisible-characters.js';
+export {toUnicodeEscape, toEscapedString} from './escape-string.js';

package/rules/utils/invisible-characters.js

@@ -0,0 +1,26 @@
+/**
+Characters that a reader cannot see, or cannot tell apart from a space: bidirectional controls (as in Trojan Source), zero-width characters, the byte order mark, the soft hyphen, control characters, and every Unicode whitespace character except space, tab, and line feed. Zero-width joiners and non-joiners are left out, because emoji sequences and several scripts need them.
+
+It has no `g` flag, so it holds no state between uses. Use `matchInvisibleCharacters()` to find each one.
+*/
+export const invisibleCharacterPattern = /[[\p{Control}\p{White_Space}\u{AD}\u{61C}\u{200B}\u{200E}\u{200F}\u{202A}-\u{202E}\u{2060}\u{2066}-\u{2069}\u{FEFF}]--[\t\n ]]/v;
+
+/**
+Every invisible character in `text`, as matches with an `index`.
+
+@param {string} text
+@returns {IterableIterator<RegExpExecArray>}
+*/
+export function matchInvisibleCharacters(text) {
+	return text.matchAll(new RegExp(invisibleCharacterPattern, 'gv'));
+}
+
+/**
+Whether `text` has an invisible character.
+
+@param {string} text
+@returns {boolean}
+*/
+export function hasInvisibleCharacter(text) {
+	return invisibleCharacterPattern.test(text);
+}