eslint-soml 0.0.3 → 0.0.4

package/index.d.ts

@@ -1,4 +1,28 @@
 import type {ESLint, Linter} from 'eslint';
+import type {LanguageOptions, RuleVisitor} from '@eslint/core';
+import type {
+	CustomRuleDefinitionType,
+	CustomRuleTypeDefinitions,
+	CustomRuleVisitorWithExit,
+	TextSourceCodeBase,
+} from '@eslint/plugin-kit';
+import type {
+	Node,
+	DocumentNode,
+	ObjectNode,
+	MemberNode,
+	ArrayNode,
+	KeyNode,
+	StringNode,
+	IntegerNode,
+	FloatNode,
+	BooleanNode,
+	NullNode,
+	InstantNode,
+	DurationNode,
+	Token,
+	Comment,
+} from 'soml-lang';
 
 export type {
 	Node,
@@ -22,6 +46,181 @@ export type {
 	SourceLocation,
 } from 'soml-lang';
 
+/**
+A node, a token, or a comment of a SOML document.
+*/
+export type SomlSyntaxElement = Node | Token | Comment;
+
+type TokenOptions = {
+	/**
+	Whether comments count as tokens.
+
+	@default false
+	*/
+	readonly includeComments?: boolean;
+};
+
+type TokenOptionsWithoutComments = TokenOptions & {readonly includeComments?: false};
+type TokenOptionsWithComments = TokenOptions & {readonly includeComments: true};
+
+/**
+The source code of a SOML document, which a rule gets as `context.sourceCode`.
+
+It has the methods of `TextSourceCodeBase` from `@eslint/plugin-kit`, such as `getText()`, `getLoc()`, `getRange()`, and `getLocFromIndex()`, and the methods below. A token method finds a token in source order and returns `null` when there is none, like ESLint's own `SourceCode`. It takes only the `includeComments` option.
+
+@example
+```
+import type {SomlRuleDefinition} from 'eslint-soml';
+
+const rule: SomlRuleDefinition = {
+	meta: {
+		type: 'problem',
+		messages: {
+			trailingComma: 'Remove the comma after the last item.',
+		},
+	},
+	create(context) {
+		return {
+			Array(node) {
+				const lastToken = context.sourceCode.getLastToken(node);
+				const beforeLast = lastToken && context.sourceCode.getTokenBefore(lastToken);
+
+				if (beforeLast?.value === ',') {
+					context.report({loc: beforeLast.loc, messageId: 'trailingComma'});
+				}
+			},
+		};
+	},
+};
+```
+*/
+export interface SomlSourceCode extends TextSourceCodeBase<{
+	LangOptions: LanguageOptions;
+	RootNode: DocumentNode;
+	SyntaxElementWithLoc: SomlSyntaxElement;
+	ConfigNode: Comment;
+}> {
+	/**
+	Marks the source code as SOML, so a rule that works on several languages can tell, as with `context.sourceCode.parserServices?.isSOML`.
+	*/
+	readonly parserServices: {readonly isSOML: true};
+
+	/**
+	The parent of a node, or `undefined` for the `Document` node. Nodes have no `parent` property.
+	*/
+	getParent(node: Node): Node | undefined;
+
+	/**
+	Every comment, in source order.
+	*/
+	getAllComments(): readonly Comment[];
+
+	/**
+	The token before a node, token, or comment.
+	*/
+	getTokenBefore(nodeOrToken: SomlSyntaxElement, options?: TokenOptionsWithoutComments): Token | null;
+	getTokenBefore(nodeOrToken: SomlSyntaxElement, options: TokenOptionsWithComments): Token | Comment | null;
+	getTokenBefore(nodeOrToken: SomlSyntaxElement, options?: TokenOptions): Token | Comment | null;
+
+	/**
+	The token after a node, token, or comment.
+	*/
+	getTokenAfter(nodeOrToken: SomlSyntaxElement, options?: TokenOptionsWithoutComments): Token | null;
+	getTokenAfter(nodeOrToken: SomlSyntaxElement, options: TokenOptionsWithComments): Token | Comment | null;
+	getTokenAfter(nodeOrToken: SomlSyntaxElement, options?: TokenOptions): Token | Comment | null;
+
+	/**
+	The first token inside a node.
+	*/
+	getFirstToken(node: Node, options?: TokenOptionsWithoutComments): Token | null;
+	getFirstToken(node: Node, options: TokenOptionsWithComments): Token | Comment | null;
+	getFirstToken(node: Node, options?: TokenOptions): Token | Comment | null;
+
+	/**
+	The last token inside a node.
+	*/
+	getLastToken(node: Node, options?: TokenOptionsWithoutComments): Token | null;
+	getLastToken(node: Node, options: TokenOptionsWithComments): Token | Comment | null;
+	getLastToken(node: Node, options?: TokenOptions): Token | Comment | null;
+
+	/**
+	Every token inside a node, in source order.
+	*/
+	getTokens(node: Node, options?: TokenOptionsWithoutComments): Token[];
+	getTokens(node: Node, options: TokenOptionsWithComments): Array<Token | Comment>;
+	getTokens(node: Node, options?: TokenOptions): Array<Token | Comment>;
+}
+
+type ValueParent = MemberNode | ArrayNode;
+type CollectionParent = DocumentNode | ValueParent;
+
+/**
+The listeners that a rule for SOML returns, with the type of each node and of its parent.
+*/
+export interface SomlRuleVisitor extends RuleVisitor, CustomRuleVisitorWithExit<{
+	Document?(node: DocumentNode): void;
+	Object?(node: ObjectNode, parent: CollectionParent): void;
+	Member?(node: MemberNode, parent: ObjectNode): void;
+	Key?(node: KeyNode, parent: MemberNode): void;
+	Array?(node: ArrayNode, parent: CollectionParent): void;
+	String?(node: StringNode, parent: ValueParent): void;
+	Integer?(node: IntegerNode, parent: ValueParent): void;
+	Float?(node: FloatNode, parent: ValueParent): void;
+	Boolean?(node: BooleanNode, parent: ValueParent): void;
+	Null?(node: NullNode, parent: ValueParent): void;
+	Instant?(node: InstantNode, parent: ValueParent): void;
+	Duration?(node: DurationNode, parent: ValueParent): void;
+}> {}
+
+export type SomlRuleDefinitionTypeOptions = CustomRuleTypeDefinitions;
+
+/**
+The type of a rule for SOML files, which gets a `SomlSourceCode` and returns a `SomlRuleVisitor`.
+
+@example
+```
+import type {SomlRuleDefinition} from 'eslint-soml';
+
+const rule: SomlRuleDefinition = {
+	meta: {
+		type: 'suggestion',
+		messages: {
+			tooLong: 'The key `{{key}}` is longer than 40 characters.',
+		},
+	},
+	create(context) {
+		return {
+			Key(node) {
+				if (node.value.length > 40) {
+					context.report({node, messageId: 'tooLong', data: {key: node.value}});
+				}
+			},
+		};
+	},
+};
+```
+*/
+export type SomlRuleDefinition<Options extends Partial<SomlRuleDefinitionTypeOptions> = {}> = CustomRuleDefinitionType<{
+	LangOptions: LanguageOptions;
+	Code: SomlSourceCode;
+	Visitor: SomlRuleVisitor;
+	Node: SomlSyntaxElement;
+}, Options>;
+
+/**
+The `context` of a rule for SOML files, for a helper that a rule passes it to.
+
+@example
+```
+import type {SomlRuleContext, StringNode} from 'eslint-soml';
+
+function isWrittenEscaped(context: SomlRuleContext, node: StringNode): boolean {
+	return context.sourceCode.getText(node).startsWith('"');
+}
+```
+*/
+export type SomlRuleContext<Options extends Partial<SomlRuleDefinitionTypeOptions> = {}> = Parameters<SomlRuleDefinition<Options>['create']>[0];
+
 declare const eslintSoml: ESLint.Plugin & {
 	configs: {
 		recommended: Linter.Config;

package/language/soml-source-code.js

@@ -13,6 +13,15 @@ import {visitorKeys} from 'soml-lang';
 
 const commentParser = new ConfigCommentParser();
 const INLINE_CONFIG = /^\s*eslint(?:-enable|-disable(?:(?:-next)?-line)?)?(?:\s|$)/v;
+const RULE_CONFIG = /^\s*eslint(?:\s|$)/v;
+// What separates a directive from its justification, as ESLint splits it.
+const JUSTIFICATION = /\s-{2,}\s/v;
+
+/*
+Whether a comment is a directive. A `#` comment is the usual comment style, so one that starts with `eslint` in prose, as in `# eslint version to install`, is not a rule configuration. A rule configuration always has a `:`, so a `#` comment without one before its justification is not a directive.
+*/
+const isInlineConfig = comment => INLINE_CONFIG.test(comment.value)
+	&& !(comment.type === 'Line' && RULE_CONFIG.test(comment.value) && !comment.value.split(JUSTIFICATION, 1)[0].includes(':'));
 
 const isComment = item => item.type === 'Line' || item.type === 'Block';
 
@@ -58,10 +67,20 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 	*/
 	#inlineConfigComments;
 	/**
+	Where each line starts, found once, when it is first needed.
+
+	@type {number[] | undefined}
+	*/
+	#lineStarts;
+	/**
 	@type {DocumentNode}
 	*/
 	ast;
 	visitorKeys = visitorKeys;
+	/**
+	Marks the source code as SOML, so a rule that works on several languages can tell, as `eslint-plugin-yml` and `eslint-plugin-toml` do with `isYAML` and `isTOML`.
+	*/
+	parserServices = {isSOML: true};
 
 	/**
 	@param {{text: string, ast: DocumentNode}} options
@@ -113,6 +132,49 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 		return null;
 	}
 
+	/**
+	The 1-based line and 0-based column of an offset.
+
+	This replaces the method of `TextSourceCodeBase`, which searches the rest of the text for a line feed again for every offset on the last line of a file with no line feed at the end, so a rule with many problems on that line takes quadratic time.
+
+	@param {number} index
+	@returns {{line: number, column: number}}
+	*/
+	getLocFromIndex(index) {
+		if (typeof index !== 'number') {
+			throw new TypeError('Expected `index` to be a number.');
+		}
+
+		if (index < 0 || index > this.text.length) {
+			throw new RangeError(`Index out of range (requested index ${index}, but source text has length ${this.text.length}).`);
+		}
+
+		if (!this.#lineStarts) {
+			this.#lineStarts = [0];
+
+			for (let lineFeed = this.text.indexOf('\n'); lineFeed !== -1; lineFeed = this.text.indexOf('\n', lineFeed + 1)) {
+				this.#lineStarts.push(lineFeed + 1);
+			}
+		}
+
+		// The last line that starts at or before `index`.
+		const lineStarts = this.#lineStarts;
+		let low = 0;
+		let high = lineStarts.length - 1;
+
+		while (low < high) {
+			const middle = Math.ceil((low + high) / 2);
+
+			if (lineStarts[middle] <= index) {
+				low = middle;
+			} else {
+				high = middle - 1;
+			}
+		}
+
+		return {line: low + 1, column: index - lineStarts[low]};
+	}
+
 	/**
 	@returns {Iterable<VisitNodeStep>}
 	*/
@@ -162,6 +224,7 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 	}
 
 	// TODO: Add a `comments` property that holds `this.ast.comments` when ESLint ships https://github.com/eslint/rfcs/pull/150. It adds `comments` to `SourceCode` and `TextSourceCodeBase`, deprecates `getAllComments()`, and makes `no-irregular-whitespace` work on any language that has `comments`. Then use `comments` in the rules, too.
+
 	/**
 	@returns {readonly Comment[]}
 	*/
@@ -173,7 +236,7 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 	@returns {Comment[]}
 	*/
 	getInlineConfigNodes() {
-		this.#inlineConfigComments ??= this.ast.comments.filter(comment => INLINE_CONFIG.test(comment.value));
+		this.#inlineConfigComments ??= this.ast.comments.filter(comment => isInlineConfig(comment));
 		return this.#inlineConfigComments;
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eslint-soml",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"description": "ESLint plugin for SOML, a config format for humans",
 	"license": "MIT",
 	"repository": "github:soml-lang/eslint-soml",
@@ -51,20 +51,20 @@
 		"style"
 	],
 	"dependencies": {
+		"@eslint/core": "^1.2.1",
 		"@eslint/plugin-kit": "^0.7.3",
-		"soml-lang": "^0.0.4"
+		"soml-lang": "^0.0.5"
 	},
 	"devDependencies": {
 		"@babel/code-frame": "^8.0.6",
 		"@eslint-community/eslint-utils": "^4.10.1",
-		"@eslint/core": "^1.2.1",
 		"@typescript-eslint/types": "^8.71.1",
 		"enquirer": "^2.4.1",
 		"eslint": "^10.12.0",
 		"eslint-config-xo": "^5.0.0",
 		"eslint-doc-generator": "^3.7.1",
 		"eslint-plugin-eslint-plugin": "^7.6.2",
-		"eslint-plugin-jsdoc": "^65.2.1",
+		"eslint-plugin-jsdoc": "^65.2.4",
 		"indent-string": "^5.0.0",
 		"markdownlint-cli": "^0.49.1",
 		"nano-spawn": "^2.1.0",

package/readme.md

@@ -16,7 +16,7 @@ npm install --save-dev eslint eslint-soml
 
 **Requires Node.js 22.13 or later, ESLint `>=10.4`, [flat config](https://eslint.org/docs/latest/use/configure/configuration-files), and [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c#how-can-i-make-my-typescript-project-output-esm).**
 
-The parser needs `Temporal` for instants and durations, and Node.js 26 and later have it built in. On older versions, linting a file with an instant or a duration fails, unless a [`Temporal` polyfill](https://github.com/fullcalendar/temporal-polyfill) is loaded first. Make `import 'temporal-polyfill/global';` the first import in `eslint.config.js`, before `eslint-soml`.
+The rules of this plugin do not need `Temporal`, so they work on every supported Node.js version, also for files with instants and durations. Only reading the `value` of an `Instant` or `Duration` node needs it, as in your own rule or in a `no-restricted-syntax` selector that matches on `value`, such as `[value=1]`. Node.js 26 and later have `Temporal` built in. On older versions, load a [`Temporal` polyfill](https://github.com/fullcalendar/temporal-polyfill) first: make `import 'temporal-polyfill/global';` the first import in `eslint.config.js`, before `eslint-soml`.
 
 ## Usage
 
@@ -61,7 +61,7 @@ Disable a rule with a comment, in either comment style:
 '404': 'Not found' /* eslint-disable-line soml/prefer-bare-keys */
 ```
 
-The [`reportUnusedDisableDirectives`](https://eslint.org/docs/latest/use/configure/configuration-files#report-unused-disable-directives) and [`reportUnusedInlineConfigs`](https://eslint.org/docs/latest/use/configure/configuration-files#report-unused-inline-configs) linter options work for `.soml` files, and so do the rules of [`@eslint-community/eslint-plugin-eslint-comments`](https://github.com/eslint-community/eslint-plugin-eslint-comments), such as `no-unlimited-disable`.
+The [`reportUnusedDisableDirectives`](https://eslint.org/docs/latest/use/configure/configuration-files#report-unused-disable-directives) and [`reportUnusedInlineConfigs`](https://eslint.org/docs/latest/use/configure/configuration-files#report-unused-inline-configs) linter options work for `.soml` files, and so do the rules of [`@eslint-community/eslint-plugin-eslint-comments`](https://github.com/eslint-community/eslint-plugin-eslint-comments), such as `no-unlimited-disable`. Those rules follow JavaScript, where a line comment holds only `eslint-disable-line` and `eslint-disable-next-line`, so some of them, such as `no-unlimited-disable` and `no-use`, do not check `# eslint-disable` and `# eslint-enable`. Write those as `/* … */` comments to have them checked.
 
 ESLint's [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax) rule works too. For example, to disallow a key named `password`:
 
@@ -86,6 +86,54 @@ export default defineConfig([
 ]);
 ```
 
+A selector can also check a value under a given key, which catches settings that are risky in production:
+
+```js
+'no-restricted-syntax': [
+	'error',
+	{
+		selector: 'Member:has(> Key[value=/^(allowed-origins|cors-origins?)$/]) String[value="*"]',
+		message: 'Allow only known origins.',
+	},
+	{
+		selector: 'Member:has(> Key[value=/^(verify-ssl|ssl-verify|tls-verify)$/]) > Boolean[value=false]',
+		message: 'Do not turn off TLS verification.',
+	},
+	{
+		selector: 'Member:has(> Key[value=/^(host|bind|listen)$/]) > String[value="0.0.0.0"]',
+		message: 'Bind to a specific address.',
+	},
+	{
+		// Only at the top level.
+		selector: 'Document > Object > Member > Key[value="debug"]',
+		message: 'Set `debug` in the environment, not in the file.',
+	},
+],
+```
+
+### SOML in Markdown
+
+To lint the `` ```soml `` code blocks in Markdown files, add the processor of [`@eslint/markdown`](https://github.com/eslint/markdown) before the preset. The blocks are linted as `.soml` files, and `--fix` writes the fixes back, also in an indented block:
+
+```js
+import markdown from '@eslint/markdown';
+import soml from 'eslint-soml';
+import {defineConfig} from 'eslint/config';
+
+export default defineConfig([
+	{
+		files: ['**/*.md'],
+		plugins: {
+			markdown,
+		},
+		processor: 'markdown/markdown',
+	},
+	soml.configs.recommended,
+]);
+```
+
+A block that shows a mistake on purpose can be skipped with `<!-- eslint-skip -->` on the line before it.
+
 ## Rules
 
 <!-- Do not manually modify this list. Run: `npm run fix:eslint-docs` -->
@@ -111,7 +159,7 @@ export default defineConfig([
 | [no-escapes-in-paths](docs/rules/no-escapes-in-paths.md)                                             | Disallow `\n` and `\t` escapes in Windows paths.                                | ✅ ☑️ |    | 💡 |
 | [no-float-trailing-zeros](docs/rules/no-float-trailing-zeros.md)                                     | Disallow trailing zeros in the fraction of a float.                             | ✅    |    | 💡 |
 | [no-invisible-characters](docs/rules/no-invisible-characters.md)                                     | Disallow invisible characters in strings, keys, and comments.                   | ✅ ☑️ | 🔧 |    |
-| [no-loss-of-precision](docs/rules/no-loss-of-precision.md)                                           | Disallow floats that cannot be stored exactly as written.                       | ✅ ☑️ |    |    |
+| [no-loss-of-precision](docs/rules/no-loss-of-precision.md)                                           | Disallow floats whose written digits are lost when they are stored.             | ✅ ☑️ |    |    |
 | [no-misplaced-block-string-delimiters](docs/rules/no-misplaced-block-string-delimiters.md)           | Disallow a block string delimiter at the end of a content line.                 | ✅ ☑️ |    |    |
 | [no-mixed-number-types](docs/rules/no-mixed-number-types.md)                                         | Disallow arrays that mix ints and floats.                                       | ✅    |    | 💡 |
 | [no-negative-zero](docs/rules/no-negative-zero.md)                                                   | Disallow a sign on zero.                                                        | ✅    | 🔧 |    |
@@ -122,7 +170,7 @@ export default defineConfig([
 | [no-zero-duration-parts](docs/rules/no-zero-duration-parts.md)                                       | Disallow duration parts that are zero.                                          | ✅    | 🔧 |    |
 | [numeric-separators-style](docs/rules/numeric-separators-style.md)                                   | Enforce the grouping of digits with `_` in decimal numbers.                     | ✅    | 🔧 |    |
 | [prefer-bare-keys](docs/rules/prefer-bare-keys.md)                                                   | Prefer bare keys when a key does not need quotes.                               | ✅    | 🔧 |    |
-| [prefer-literal-strings](docs/rules/prefer-literal-strings.md)                                       | Prefer literal strings, `'…'`, when a string has no escapes.                    | ✅    | 🔧 |    |
+| [prefer-literal-strings](docs/rules/prefer-literal-strings.md)                                       | Prefer literal strings, `'…'`, when a string does not need escapes.             | ✅    | 🔧 |    |
 | [prefer-utc-instants](docs/rules/prefer-utc-instants.md)                                             | Prefer instants in UTC.                                                         |      | 🔧 |    |
 | [sort-keys](docs/rules/sort-keys.md)                                                                 | Require object keys to be sorted.                                               |      | 🔧 |    |
 | [spaced-comment](docs/rules/spaced-comment.md)                                                       | Require a space after `#` and `/*`, and before `*/`.                            | ✅    | 🔧 |    |
@@ -201,6 +249,48 @@ In Visual Studio Code, the [ESLint extension](https://marketplace.visualstudio.c
 }
 ```
 
+## Writing rules
+
+A rule for SOML files gets the syntax tree of [`soml-lang`](https://github.com/soml-lang/soml-javascript#parsetreetext), which documents every node. This package exports the types of the nodes, and `SomlRuleDefinition`, `SomlRuleVisitor`, `SomlSourceCode`, and `SomlRuleContext` (for a helper that a rule passes its `context` to) for a rule:
+
+```js
+/**
+@type {import('eslint-soml').SomlRuleDefinition}
+*/
+const rule = {
+	meta: {
+		type: 'suggestion',
+		messages: {
+			tooLong: 'The key `{{key}}` is longer than 40 characters.',
+		},
+	},
+	create(context) {
+		return {
+			Key(node) {
+				if (node.value.length > 40) {
+					context.report({node, messageId: 'tooLong', data: {key: node.value}});
+				}
+			},
+		};
+	},
+};
+```
+
+The nodes hold decoded values, and the source text keeps the spelling:
+
+- `Key` and `String` have the decoded `value`, so `a`, `'a'`, and `"\u{61}"` all have the value `a`. Their `style` is how they are written: `'bare'` (a key only), `'literal'` for `'…'`, or `'escaped'` for `"…"`. A `String` also has `block`, which is `true` for `'''` and `"""`.
+- `Integer` has a `bigint` `value` and its `radix`, so `0xFF` and `255` have the same value. `Float` and `Boolean` have a `value`, and `Null` has none.
+- `context.sourceCode.getText(node)` gives the source text, such as `0xFF` or `"\u{61}"`, for a rule about spelling.
+
+`context.sourceCode` has the methods of `TextSourceCodeBase` from `@eslint/plugin-kit`, such as `getText()`, `getLoc()`, `getRange()`, and `getLocFromIndex()`, and these:
+
+- `getParent(node)` returns the parent of a node, or `undefined` for the `Document` node. Nodes have no `parent` property. A listener also gets the parent as its second argument.
+- `getAllComments()` returns every comment, in source order.
+- `getTokenBefore()`, `getTokenAfter()`, `getFirstToken()`, `getLastToken()`, and `getTokens()` find tokens in source order. They take only the `includeComments` option, and return `null` when there is no token, like ESLint's own `SourceCode`.
+- `parserServices.isSOML` is `true`, so a rule that works on several languages can tell a SOML file, with `context.sourceCode.parserServices?.isSOML`.
+
+Reading the `value` of an `Instant` or a `Duration` node needs `Temporal`, and so does spreading such a node. Check the type of a node before you read its `value`, and use `parts` or the source text of a duration when you can.
+
 ## Related
 
 - [soml-javascript](https://github.com/soml-lang/soml-javascript) - The reference parser and serializer for SOML

package/rules/no-block-string-edge-blank-lines.js

@@ -1,4 +1,4 @@
-import {trimEnd} from './utils/index.js';
+import {getLines, trimEnd} from './utils/index.js';
 
 /**
 @import {SomlContext} from './rule/soml-context.js';
@@ -23,15 +23,11 @@ const create = context => {
 			return;
 		}
 
-		const lines = sourceCode.getText(node).split('\n');
+		const lines = getLines(context, node);
 		// The first line holds the opening delimiter, and the last line the closing one.
-		const content = lines.slice(1, -1);
+		const content = lines.slice(1, -1).map(line => line.text);
 		// Where each content line starts, and then where the closing line starts.
-		const lineStarts = [sourceCode.getRange(node)[0] + lines[0].length + 1];
-
-		for (const line of content) {
-			lineStarts.push(lineStarts.at(-1) + line.length + 1);
-		}
+		const lineStarts = lines.slice(1).map(line => line.start);
 
 		const firstContent = content.findIndex(line => !isBlank(line));
 		// With no content, every line is a leading blank line.

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

@@ -1,4 +1,4 @@
-import {trimEnd} from './utils/index.js';
+import {getLines, trimEnd} from './utils/index.js';
 
 /**
 @import {SomlContext} from './rule/soml-context.js';
@@ -21,25 +21,20 @@ const create = context => {
 			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 content = trimEnd(line, ' \t');
+		for (const {text, start} of getLines(context, node).slice(1, -1)) {
+			const content = trimEnd(text, ' \t');
 
 			// A blank line becomes an empty line, so its whitespace is not part of the value.
-			if (content !== '' && content.length < line.length) {
+			if (content !== '' && content.length < text.length) {
 				yield {
 					loc: {
-						start: sourceCode.getLocFromIndex(offset + content.length),
-						end: sourceCode.getLocFromIndex(offset + line.length),
+						start: sourceCode.getLocFromIndex(start + content.length),
+						end: sourceCode.getLocFromIndex(start + text.length),
 					},
 					messageId: MESSAGE_ID,
 				};
 			}
-
-			offset += line.length + 1;
 		}
 	});
 };

package/rules/no-duplicate-array-items.js

@@ -1,5 +1,5 @@
 import {stringifyValue} from 'soml-lang';
-import {hasAdjacentComment, isPunctuator} from './utils/index.js';
+import {escapeInvisibleCharacters, hasAdjacentComment, isPunctuator} from './utils/index.js';
 
 /**
 @import {SomlContext} from './rule/soml-context.js';
@@ -72,8 +72,8 @@ const create = context => {
 				node: item,
 				messageId: MESSAGE_ID_ERROR,
 				data: {
-					// A block string spans lines, so it is shown as a one-line string with the same value.
-					item: item.block ? stringifyValue(item.value) : sourceCode.getText(item),
+					// A block string spans lines, so it is shown as a one-line string with the same value. Canonical form writes a bidirectional control as it is, so it is escaped, as an escape in the block string was.
+					item: item.block ? escapeInvisibleCharacters(stringifyValue(item.value)) : sourceCode.getText(item),
 					line: sourceCode.getLoc(first).start.line,
 				},
 				// Removing an item changes the value, so it is a suggestion. It is left out when it would remove a comment.

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

@@ -81,7 +81,7 @@ const config = {
 	meta: {
 		type: 'problem',
 		docs: {
-			description: 'Disallow floats that cannot be stored exactly as written.',
+			description: 'Disallow floats whose written digits are lost when they are stored.',
 			recommended: 'unopinionated',
 		},
 		messages,

package/rules/no-misplaced-block-string-delimiters.js

@@ -1,4 +1,4 @@
-import {trimEnd} from './utils/index.js';
+import {getLines} from './utils/index.js';
 
 /**
 @import {SomlContext} from './rule/soml-context.js';
@@ -22,6 +22,33 @@ function isClosingQuote(line, index, delimiter) {
 	return runs.filter(run => run.length === delimiter.length).length % 2 === 1;
 }
 
+/*
+What may follow a closing delimiter on its line: whitespace, commas, closing brackets, and a comment. It is sticky, so it matches from `lastIndex`, which is set before every use.
+*/
+const AFTER_DELIMITER = /[\t ]*(?:[,\]\}][\t ]*)*(?:(?:#|\/\*).*)?$/vy;
+
+/*
+Where a misplaced delimiter starts on a content line, or `undefined`: a run of exactly the delimiter's length with only what may follow a closing delimiter after it, as TOML and Java allow, in `Welcome!'''`, `Hi'''}`, or `Welcome!''' # greeting`. Only the first run with such a tail is checked, because what follows it is a comment or brackets.
+*/
+function getMisplacedDelimiterIndex(line, delimiter, isEscaped) {
+	for (const match of line.matchAll(QUOTE_RUNS[delimiter[0]])) {
+		let {index} = match;
+		const end = index + match[0].length;
+		AFTER_DELIMITER.lastIndex = end;
+
+		if (!AFTER_DELIMITER.test(line)) {
+			continue;
+		}
+
+		// In a `"""` block, `\"` is an escaped quote, so it is not part of the run.
+		if (isEscaped && ESCAPING_BACKSLASHES.test(line.slice(0, index))) {
+			index++;
+		}
+
+		return index > 0 && end - index === delimiter.length && !isClosingQuote(line, index, delimiter) ? index : undefined;
+	}
+}
+
 /**
 @param {SomlContext} context
 */
@@ -33,50 +60,24 @@ const create = context => {
 			return;
 		}
 
-		const lines = sourceCode.getText(node).split('\n');
+		const lines = getLines(context, node);
 		// The first line is the opening delimiter, so it is a run of one quote character.
-		const delimiter = lines[0];
-		let offset = sourceCode.getRange(node)[0] + delimiter.length + 1;
+		const delimiter = lines[0].text;
 
 		// The last line holds the closing delimiter. Only the first misplaced delimiter is reported, because the lines after it, such as the opening of another block string, are content only because of it.
-		for (const line of lines.slice(1, -1)) {
-			// A run of exactly the delimiter's length at the end of a line, as TOML and Java allow, optionally followed by a comma.
-			let content = trimEnd(line, ' \t');
-
-			if (content.endsWith(',')) {
-				content = trimEnd(content.slice(0, -1), ' \t');
-			}
-
-			// Where the run of quotes at the end starts.
-			let index = content.length;
-
-			while (index > 0 && content[index - 1] === delimiter[0]) {
-				index--;
-			}
-
-			// In a `"""` block, `\"` is an escaped quote, so it is not part of the run.
-			if (node.style === 'escaped' && content.length - index >= delimiter.length && ESCAPING_BACKSLASHES.test(content.slice(0, index))) {
-				index++;
-			}
-
-			if (
-				index > 0
-				&& content.length - index === delimiter.length
-				&& !isClosingQuote(content, index, delimiter)
-			) {
-				const start = offset + index;
+		for (const {text, start} of lines.slice(1, -1)) {
+			const index = getMisplacedDelimiterIndex(text, delimiter, node.style === 'escaped');
 
+			if (index !== undefined) {
 				return {
 					loc: {
-						start: sourceCode.getLocFromIndex(start),
-						end: sourceCode.getLocFromIndex(start + delimiter.length),
+						start: sourceCode.getLocFromIndex(start + index),
+						end: sourceCode.getLocFromIndex(start + index + delimiter.length),
 					},
 					messageId: MESSAGE_ID,
 					data: {delimiter},
 				};
 			}
-
-			offset += line.length + 1;
 		}
 	});
 };

package/rules/prefer-literal-strings.js

@@ -66,7 +66,7 @@ const config = {
 	meta: {
 		type: 'suggestion',
 		docs: {
-			description: 'Prefer literal strings, `\'…\'`, when a string has no escapes.',
+			description: 'Prefer literal strings, `\'…\'`, when a string does not need escapes.',
 			recommended: true,
 		},
 		fixable: 'code',

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

@@ -31,6 +31,7 @@ Convert a problem from a listener to an ESLint problem. A suggestion gets the `d
 */
 export default function toEslintProblem(somlProblem) {
 	const {fix, suggest, ...problem} = somlProblem;
+
 	/**
 	@type {EslintProblem}
 	*/

package/rules/sort-keys.js

@@ -59,10 +59,9 @@ function compareNatural(first, second) {
 			return firstCodePoint - secondCodePoint;
 		}
 
-		// The two code points are equal, so they have the same length.
-		const length = firstCodePoint > 0xFF_FF ? 2 : 1;
-		firstIndex += length;
-		secondIndex += length;
+		// The two code points are equal, so a surrogate pair is followed by the same low surrogate in both.
+		firstIndex++;
+		secondIndex++;
 	}
 
 	// A key that ends first comes first, as `a` before `a1`.
@@ -94,6 +93,9 @@ const create = context => {
 		return commentLines;
 	};
 
+	// Whether the fix is allowed, found once per file, because the directives would be parsed again for every object.
+	let isFixable;
+
 	/**
 	Whether a blank line separates two members. A line in a comment is not blank.
 
@@ -152,7 +154,7 @@ const create = context => {
 						sortName: natural ? 'natural' : 'code point',
 					},
 					// The fix sorts the whole object at once, so one run of `--fix` is enough, and only the first problem carries it. Giving every problem the same fix would build it once per problem.
-					fix: isFirst && !isDisabledAnywhere(context) ? reorderMembers(context, node.members, groups.flatMap(group => group.toSorted(compareMembers))) : undefined,
+					fix: isFirst && (isFixable ??= !isDisabledAnywhere(context)) ? reorderMembers(context, node.members, groups.flatMap(group => group.toSorted(compareMembers))) : undefined,
 				};
 
 				isFirst = false;

package/rules/utils/get-key-words.js

@@ -1,11 +1,11 @@
 /**
-The words of a key, in lowercase: `maxHeapSize`, `max-heap-size`, and `max_heap_size` all give `max`, `heap`, and `size`. An acronym is a word too, so `maxRAMSize` gives `max`, `ram`, and `size`. Every character that is not a letter or a digit separates words, so a quoted key works too, as in `'spark.executor.memory'` (Spark) or `'php_admin_value[memory_limit]'` (PHP-FPM). A separator at an end or next to another one makes no empty word, so `_size` is one word.
+The words of a key, in lowercase: `maxHeapSize`, `max-heap-size`, and `max_heap_size` all give `max`, `heap`, and `size`. An acronym is a word too, so `maxRAMSize` gives `max`, `ram`, and `size`. A word after an acronym has at least two lowercase letters, so a plural acronym, as in `maxCPUs`, stays one word. Every character that is not a letter or a digit separates words, so a quoted key works too, as in `'spark.executor.memory'` (Spark) or `'php_admin_value[memory_limit]'` (PHP-FPM). A separator at an end or next to another one makes no empty word, so `_size` is one word.
 
 @param {string} key
 @returns {string[]}
 */
 export default function getKeyWords(key) {
-	return key.split(/[^\p{Letter}\p{Number}]|(?<=[\da-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/v)
+	return key.split(/[^\p{Letter}\p{Number}]|(?<=[\da-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z]{2})/v)
 		.filter(word => word !== '')
 		.map(word => word.toLowerCase());
 }

package/rules/utils/get-lines.js

@@ -0,0 +1,24 @@
+/**
+@import {SomlContext} from '../rule/soml-context.js';
+@import {Node} from 'soml-lang';
+*/
+
+/**
+The lines of the source text of `node`, each with the offset where it starts. In a block string, the first line holds the opening delimiter, and the last line the closing one.
+
+@param {SomlContext} context
+@param {Node} node
+@returns {Array<{text: string, start: number}>}
+*/
+export default function getLines(context, node) {
+	const {sourceCode} = context;
+	const lines = [];
+	let [start] = sourceCode.getRange(node);
+
+	for (const text of sourceCode.getText(node).split('\n')) {
+		lines.push({text, start});
+		start += text.length + 1;
+	}
+
+	return lines;
+}

package/rules/utils/index.js

@@ -9,6 +9,7 @@ export {reorderMembers, hasAdjacentComment} from './reorder-members.js';
 export {default as trimWhitespace} from './trim-whitespace.js';
 export {isComment, isPunctuator} from './token.js';
 export {default as trimEnd} from './trim-end.js';
+export {default as getLines} from './get-lines.js';
 export {default as hasDoubledBackslashes} from './has-doubled-backslashes.js';
 export {default as getKeyWords} from './get-key-words.js';
 export {default as isDisabledAnywhere} from './is-disabled-anywhere.js';

package/rules/utils/invisible-characters.js

@@ -1,10 +1,11 @@
 /**
 Characters that a reader cannot see, or cannot tell apart from a space: bidirectional controls (as in Trojan Source), zero-width characters (including the invisible math operators U+2061 to U+2064), the Hangul fillers, which show as blank, other invisible format characters (U+180E and U+206A to U+206F), 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.
 
-Tag characters are invisible too, and can hide text, as in ASCII smuggling. They are left out only in an emoji tag sequence, which is U+1F3F4 and then tags up to U+E007F, as in the flag of Scotland. Such a sequence is short, so the lookbehind is bounded.
+Tag characters are invisible too, and can hide text, as in ASCII smuggling. They are left out only in an emoji tag sequence, which is U+1F3F4, at most six tags, and U+E007F, as in the flag of Scotland. So a tag is reported when more than five tags or no U+1F3F4 come before it, or more than five tags or no U+E007F come after it.
 */
 const characters = /[[\p{Control}\p{White_Space}\u{AD}\u{61C}\u{115F}\u{1160}\u{180E}\u{200B}\u{200E}\u{200F}\u{202A}-\u{202E}\u{2060}-\u{2064}\u{2066}-\u{206F}\u{3164}\u{FEFF}\u{FFA0}]--[\t\n ]]/v;
-const tags = /(?<!\u{1F3F4}[\u{E0020}-\u{E007E}]{0,32})[\u{E0001}\u{E0020}-\u{E007F}]/v;
+const tagSpec = String.raw`[\u{E0020}-\u{E007E}]`;
+const tags = new RegExp(String.raw`\u{E0001}|(?<!\u{1F3F4}${tagSpec}{0,5})${tagSpec}|${tagSpec}(?!${tagSpec}{0,5}\u{E007F})|(?<!\u{1F3F4}${tagSpec}{1,6})\u{E007F}`, 'v');
 const invisibleCharacter = new RegExp(`${characters.source}|${tags.source}`, 'v');
 
 /**

package/rules/utils/is-disabled-anywhere.js

@@ -9,7 +9,7 @@ const commentParser = new ConfigCommentParser();
 /**
 Whether a disable directive in the document turns off the rule of `context` anywhere, as `# eslint-disable-next-line soml/format` does, or as one without rule names does.
 
-A rule whose one fix changes the whole document or a whole object leaves out that fix then. ESLint applies a fix when the problem that carries it is reported, even when the other problems are turned off, so the fix would change the lines that the directive keeps, and ESLint would then remove the directive as unused.
+A rule whose one fix changes the whole document or a whole object leaves out that fix then. ESLint applies a fix when the problem that carries it is reported, even when the other problems are turned off, so the fix would change the lines that the directive keeps, and ESLint would then remove the directive as unused. A rule cannot see the `noInlineConfig` linter option, so a directive that the option turns off still counts.
 
 @param {SomlContext} context
 @returns {boolean}