eslint-soml 0.0.4 → 0.0.5

package/index.d.ts

@@ -66,7 +66,7 @@ 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.
+It has the methods of `TextSourceCodeBase` from `@eslint/plugin-kit`, such as `getText()`, `getLoc()`, `getRange()`, and `getLocFromIndex()`, and the methods below. Token methods find tokens in source order and take only the `includeComments` option. Single-token methods return `null` when there is no token; `getTokens()` returns an array.
 
 @example
 ```
@@ -110,6 +110,16 @@ export interface SomlSourceCode extends TextSourceCodeBase<{
 	*/
 	getParent(node: Node): Node | undefined;
 
+	/**
+	Every ancestor node, from the root to the parent. Tokens and comments have no ancestors.
+
+	@example
+	```
+	const parents = context.sourceCode.getAncestors(node).map(ancestor => context.sourceCode.getParent(ancestor));
+	```
+	*/
+	getAncestors(node: SomlSyntaxElement): Node[];
+
 	/**
 	Every comment, in source order.
 	*/
@@ -158,7 +168,7 @@ 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;
+	Document?(node: DocumentNode, parent: undefined): void;
 	Object?(node: ObjectNode, parent: CollectionParent): void;
 	Member?(node: MemberNode, parent: ObjectNode): void;
 	Key?(node: KeyNode, parent: MemberNode): void;

package/index.js

@@ -28,6 +28,7 @@ const soml = {
 	meta: {
 		// `eslint-doc-generator` derives the rule prefix from this name, expecting either the `eslint-plugin-<prefix>` convention or the prefix itself. The package name does not follow that convention, so this is the prefix.
 		name: 'soml',
+		namespace: 'soml',
 		version: packageJson.version,
 	},
 	languages: {

package/language/soml-source-code.js

@@ -132,6 +132,23 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 		return null;
 	}
 
+	/**
+	The offsets where each line starts, shared by both location conversions.
+
+	@returns {number[]}
+	*/
+	#getLineStarts() {
+		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);
+			}
+		}
+
+		return this.#lineStarts;
+	}
+
 	/**
 	The 1-based line and 0-based column of an offset.
 
@@ -149,16 +166,8 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 			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;
+		const lineStarts = this.#getLineStarts();
 		let low = 0;
 		let high = lineStarts.length - 1;
 
@@ -175,6 +184,34 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 		return {line: low + 1, column: index - lineStarts[low]};
 	}
 
+	/**
+	The offset of a 1-based line and 0-based column. Use the cached line starts so repeated locations on the last line do not search for a line feed again.
+
+	@param {{line: number, column: number}} location
+	@returns {number}
+	*/
+	getIndexFromLoc(location) {
+		if (location === null || typeof location !== 'object' || typeof location.line !== 'number' || typeof location.column !== 'number') {
+			throw new TypeError('Expected `loc` to be an object with numeric `line` and `column` properties.');
+		}
+
+		const lineStarts = this.#getLineStarts();
+		if (location.line < 1 || location.line > lineStarts.length) {
+			throw new RangeError(`Line number out of range (line ${location.line} requested). Valid range: 1-${lineStarts.length}`);
+		}
+
+		const lineStartIndex = lineStarts[location.line - 1];
+		const isLastLine = location.line === lineStarts.length;
+		const lineEndIndex = isLastLine ? this.text.length : lineStarts[location.line];
+		const positionIndex = lineStartIndex + location.column;
+
+		if (location.column < 0 || (isLastLine ? positionIndex > lineEndIndex : positionIndex >= lineEndIndex)) {
+			throw new RangeError(`Column number out of range (column ${location.column} requested). Valid range for line ${location.line}: 0-${lineEndIndex - lineStartIndex + (isLastLine ? 0 : -1)}`);
+		}
+
+		return positionIndex;
+	}
+
 	/**
 	@returns {Iterable<VisitNodeStep>}
 	*/
@@ -223,7 +260,7 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 		return this.#parents.get(node);
 	}
 
-	// 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.
+	// When ESLint ships https://github.com/eslint/rfcs/pull/150, add a `comments` property holding `this.ast.comments` and use it in the rules. The new API deprecates `getAllComments()` and enables `no-irregular-whitespace` across languages.
 
 	/**
 	@returns {readonly Comment[]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eslint-soml",
-	"version": "0.0.4",
+	"version": "0.0.5",
 	"description": "ESLint plugin for SOML, a config format for humans",
 	"license": "MIT",
 	"repository": "github:soml-lang/eslint-soml",
@@ -53,20 +53,20 @@
 	"dependencies": {
 		"@eslint/core": "^1.2.1",
 		"@eslint/plugin-kit": "^0.7.3",
-		"soml-lang": "^0.0.5"
+		"soml-lang": "^0.0.7"
 	},
 	"devDependencies": {
 		"@babel/code-frame": "^8.0.6",
 		"@eslint-community/eslint-utils": "^4.10.1",
-		"@typescript-eslint/types": "^8.71.1",
+		"@typescript-eslint/types": "^8.71.2",
 		"enquirer": "^2.4.1",
-		"eslint": "^10.12.0",
-		"eslint-config-xo": "^5.0.0",
+		"eslint": "^10.13.0",
+		"eslint-config-xo": "^7.0.0",
 		"eslint-doc-generator": "^3.7.1",
 		"eslint-plugin-eslint-plugin": "^7.6.2",
-		"eslint-plugin-jsdoc": "^65.2.4",
+		"eslint-plugin-jsdoc": "^65.3.11",
 		"indent-string": "^5.0.0",
-		"markdownlint-cli": "^0.49.1",
+		"markdownlint-cli": "^0.50.0",
 		"nano-spawn": "^2.1.0",
 		"node-style-text": "^2.1.2",
 		"npm-run-all2": "^9.0.3",

package/readme.md

@@ -111,6 +111,38 @@ A selector can also check a value under a given key, which catches settings that
 ],
 ```
 
+A selector can also say what the program that reads a file does not support. SOML allows each of these values, so use only the ones your program needs:
+
+```js
+'no-restricted-syntax': [
+	'error',
+	{
+		// Such as a program that reads ints as JavaScript numbers.
+		selector: ':matches(Integer[value>9007199254740991], Integer[value<-9007199254740991])',
+		message: 'This program needs ints in the JavaScript safe integer range.',
+	},
+	{
+		// Such as a program that writes the value as JSON, where `infinity` becomes `null`.
+		selector: ':matches(Float[value="Infinity"], Float[value="-Infinity"])',
+		message: 'This program needs finite numbers.',
+	},
+	{
+		// Such as a program that uses the value as a file name.
+		selector: ':matches(String, Key)[value=/\\u0000/]',
+		message: 'This program does not support the NUL character.',
+	},
+	{
+		// Such as a program that merges the value into an object with `Object.assign()`.
+		selector: 'Key[value="__proto__"]',
+		message: 'This program does not support the key `__proto__`.',
+	},
+	{
+		selector: ':matches(Instant, Duration)',
+		message: 'This program does not support instants and durations.',
+	},
+],
+```
+
 ### 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:
@@ -145,35 +177,40 @@ A block that shows a mistake on purpose can be skipped with `<!-- eslint-skip --
 🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
 💡 Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
-| Name                                                                                                 | Description                                                                     | 💼   | 🔧 | 💡 |
-| :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ | :--- | :- | :- |
-| [format](docs/rules/format.md)                                                                       | Enforce the layout of the SOML formatter.                                       | ✅    | 🔧 |    |
-| [key-name-casing](docs/rules/key-name-casing.md)                                                     | Enforce a casing style for keys.                                                |      |    |    |
-| [no-block-string-edge-blank-lines](docs/rules/no-block-string-edge-blank-lines.md)                   | Disallow blank lines at the start and end of block strings.                     | ✅    | 🔧 |    |
-| [no-block-string-trailing-whitespace](docs/rules/no-block-string-trailing-whitespace.md)             | Disallow trailing whitespace in block strings.                                  | ✅ ☑️ |    |    |
-| [no-confusable-keys](docs/rules/no-confusable-keys.md)                                               | Disallow keys that differ only in case, `-` and `_`, or surrounding whitespace. | ✅ ☑️ |    |    |
-| [no-decimal-file-modes](docs/rules/no-decimal-file-modes.md)                                         | Disallow file modes written as decimal numbers.                                 | ✅ ☑️ |    | 💡 |
-| [no-doubled-backslashes-in-literal-strings](docs/rules/no-doubled-backslashes-in-literal-strings.md) | Disallow doubled backslashes in literal strings, such as `'^\\d+$'`.            | ✅    |    | 💡 |
-| [no-duplicate-array-items](docs/rules/no-duplicate-array-items.md)                                   | Disallow the same string twice in an array.                                     |      |    | 💡 |
-| [no-empty-keys](docs/rules/no-empty-keys.md)                                                         | Disallow empty and whitespace-only keys.                                        | ✅ ☑️ |    |    |
-| [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 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.                                                        | ✅    | 🔧 |    |
-| [no-placeholder-values](docs/rules/no-placeholder-values.md)                                         | Disallow placeholder values, such as `'changeme'`.                              | ✅    |    |    |
-| [no-quoted-keywords](docs/rules/no-quoted-keywords.md)                                               | Disallow the strings `'true'`, `'false'`, and `'null'`.                         | ✅    |    | 💡 |
-| [no-sizes-as-durations](docs/rules/no-sizes-as-durations.md)                                         | Disallow sizes that are durations, such as `memory: 512m`.                      | ✅ ☑️ |    | 💡 |
-| [no-unnormalized-keys](docs/rules/no-unnormalized-keys.md)                                           | Disallow keys that are not in a Unicode normalization form.                     | ✅ ☑️ |    |    |
-| [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 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 `*/`.                            | ✅    | 🔧 |    |
+| Name                                                                                                 | Description                                                                           | 💼   | 🔧 | 💡 |
+| :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ | :--- | :- | :- |
+| [format](docs/rules/format.md)                                                                       | Enforce the layout of the SOML formatter.                                             | ✅    | 🔧 |    |
+| [key-name-casing](docs/rules/key-name-casing.md)                                                     | Enforce a casing style for keys.                                                      |      |    |    |
+| [no-block-string-edge-blank-lines](docs/rules/no-block-string-edge-blank-lines.md)                   | Disallow blank lines at the start and end of block strings.                           | ✅    | 🔧 |    |
+| [no-block-string-trailing-whitespace](docs/rules/no-block-string-trailing-whitespace.md)             | Disallow trailing whitespace in block strings.                                        | ✅ ☑️ |    |    |
+| [no-confusable-keys](docs/rules/no-confusable-keys.md)                                               | Disallow keys that differ only in case, `-`, `_`, and `.`, or surrounding whitespace. | ✅ ☑️ |    |    |
+| [no-decimal-file-modes](docs/rules/no-decimal-file-modes.md)                                         | Disallow file modes written as decimal numbers.                                       | ✅ ☑️ |    | 💡 |
+| [no-dotted-key-collisions](docs/rules/no-dotted-key-collisions.md)                                   | Disallow quoted keys with a `.` that read as a path into an object next to them.      | ✅    |    |    |
+| [no-doubled-backslashes-in-literal-strings](docs/rules/no-doubled-backslashes-in-literal-strings.md) | Disallow doubled backslashes in literal strings, such as `'^\\d+$'`.                  | ✅    |    | 💡 |
+| [no-duplicate-array-items](docs/rules/no-duplicate-array-items.md)                                   | Disallow the same string twice in an array.                                           |      |    | 💡 |
+| [no-empty-keys](docs/rules/no-empty-keys.md)                                                         | Disallow empty and whitespace-only keys.                                              | ✅ ☑️ |    |    |
+| [no-escapes-in-literal-strings](docs/rules/no-escapes-in-literal-strings.md)                         | Disallow escapes in literal strings, such as `'Line one\nLine two'`.                  | ✅    |    | 💡 |
+| [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 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.                                                              | ✅    | 🔧 |    |
+| [no-placeholder-values](docs/rules/no-placeholder-values.md)                                         | Disallow placeholder values, such as `'changeme'`.                                    | ✅    |    |    |
+| [no-quoted-keywords](docs/rules/no-quoted-keywords.md)                                               | Disallow the strings `'true'`, `'false'`, and `'null'`.                               | ✅    |    | 💡 |
+| [no-quoted-values-in-arrays](docs/rules/no-quoted-values-in-arrays.md)                               | Disallow quoted values in an array of that type, such as `'443'` in `[80, '443']`.    | ✅    |    | 💡 |
+| [no-sizes-as-durations](docs/rules/no-sizes-as-durations.md)                                         | Disallow sizes that are durations, such as `memory: 512m`.                            | ✅ ☑️ |    | 💡 |
+| [no-surrounding-whitespace-in-keys](docs/rules/no-surrounding-whitespace-in-keys.md)                 | Disallow whitespace at the start and end of keys.                                     | ✅    |    |    |
+| [no-unnormalized-keys](docs/rules/no-unnormalized-keys.md)                                           | Disallow keys that are not in a Unicode normalization form.                           | ✅ ☑️ |    |    |
+| [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-block-strings](docs/rules/prefer-block-strings.md)                                           | Prefer block strings for strings of three lines or more.                              | ✅    | 🔧 |    |
+| [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 `*/`.                                  | ✅    | 🔧 |    |
 
 <!-- end auto-generated rules list -->
 
@@ -251,45 +288,7 @@ 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.
+See [how to write rules for SOML files](docs/writing-rules.md).
 
 ## Related
 

package/rules/index.js

@@ -6,9 +6,11 @@ export {default as 'no-block-string-edge-blank-lines'} from './no-block-string-e
 export {default as 'no-block-string-trailing-whitespace'} from './no-block-string-trailing-whitespace.js';
 export {default as 'no-confusable-keys'} from './no-confusable-keys.js';
 export {default as 'no-decimal-file-modes'} from './no-decimal-file-modes.js';
+export {default as 'no-dotted-key-collisions'} from './no-dotted-key-collisions.js';
 export {default as 'no-doubled-backslashes-in-literal-strings'} from './no-doubled-backslashes-in-literal-strings.js';
 export {default as 'no-duplicate-array-items'} from './no-duplicate-array-items.js';
 export {default as 'no-empty-keys'} from './no-empty-keys.js';
+export {default as 'no-escapes-in-literal-strings'} from './no-escapes-in-literal-strings.js';
 export {default as 'no-escapes-in-paths'} from './no-escapes-in-paths.js';
 export {default as 'no-float-trailing-zeros'} from './no-float-trailing-zeros.js';
 export {default as 'no-invisible-characters'} from './no-invisible-characters.js';
@@ -18,11 +20,14 @@ export {default as 'no-mixed-number-types'} from './no-mixed-number-types.js';
 export {default as 'no-negative-zero'} from './no-negative-zero.js';
 export {default as 'no-placeholder-values'} from './no-placeholder-values.js';
 export {default as 'no-quoted-keywords'} from './no-quoted-keywords.js';
+export {default as 'no-quoted-values-in-arrays'} from './no-quoted-values-in-arrays.js';
 export {default as 'no-sizes-as-durations'} from './no-sizes-as-durations.js';
+export {default as 'no-surrounding-whitespace-in-keys'} from './no-surrounding-whitespace-in-keys.js';
 export {default as 'no-unnormalized-keys'} from './no-unnormalized-keys.js';
 export {default as 'no-zero-duration-parts'} from './no-zero-duration-parts.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-block-strings'} from './prefer-block-strings.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';

package/rules/no-confusable-keys.js

@@ -1,4 +1,4 @@
-import {trimWhitespace} from './utils/index.js';
+import {escapeInvisibleCharacters, trimWhitespace} from './utils/index.js';
 
 /**
 @import {SomlContext} from './rule/soml-context.js';
@@ -7,13 +7,25 @@ import {trimWhitespace} from './utils/index.js';
 
 const MESSAGE_ID = 'no-confusable-keys';
 const messages = {
-	[MESSAGE_ID]: '`{{key}}` and `{{otherKey}}` are one key to a program that ignores case, `-` versus `_`, or surrounding whitespace.',
+	[MESSAGE_ID]: '`{{key}}` and `{{otherKey}}` are one key to a program that ignores case or surrounding whitespace, or that treats `-`, `_`, and `.` as the same.',
 };
 
 /*
-What many programs compare keys by: case-insensitive, with `-` and `_` the same, and without surrounding whitespace.
+What many programs compare keys by: case-insensitive, with `-`, `_`, and `.` the same, and without surrounding whitespace. Libraries that read settings from environment variables treat `.` as `_`: Spring reads `LOG_LEVEL` as `log.level`, and Viper, with its usual replacer, as both `log.level` and `log-level`.
 */
-const fold = key => trimWhitespace(key).toLowerCase().replaceAll('-', '_');
+const foldCharacter = character => {
+	const upper = character.toUpperCase();
+	const lower = upper.toLowerCase();
+	// A form that is more than one code point, such as the `SS` that `ß` uppercases to, is not a case of one letter, so keep the character as it is.
+	return [...upper].length === 1 && [...lower].length === 1 ? lower : character;
+};
+
+/*
+Lowercasing alone leaves some case variants apart, because several code points can share one uppercase form: `ς` (final sigma) does not lowercase to `σ`, `ſ` does not lowercase to `s`, and `ı` does not lowercase to `i`. Uppercasing and lowercasing each code point again reaches the form the others share. Lowercase first, so a document that a JavaScript `toLowerCase()` reader would merge, such as `İ` and `i̇`, still folds together.
+*/
+const fold = key => [...trimWhitespace(key).toLowerCase().replaceAll(/[\-.]/gv, '_')]
+	.map(character => foldCharacter(character))
+	.join('');
 
 /**
 @param {SomlContext} context
@@ -37,10 +49,10 @@ const create = context => {
 			yield {
 				node: key,
 				messageId: MESSAGE_ID,
-				// The source text shows the quotes, so a key with whitespace stays readable.
+				// The source text shows the quotes, so a key with whitespace stays readable, and a bidirectional control is escaped.
 				data: {
-					key: context.sourceCode.getText(key),
-					otherKey: context.sourceCode.getText(firstKey),
+					key: escapeInvisibleCharacters(context.sourceCode.getText(key)),
+					otherKey: escapeInvisibleCharacters(context.sourceCode.getText(firstKey)),
 				},
 			};
 		}
@@ -55,7 +67,7 @@ const config = {
 	meta: {
 		type: 'problem',
 		docs: {
-			description: 'Disallow keys that differ only in case, `-` and `_`, or surrounding whitespace.',
+			description: 'Disallow keys that differ only in case, `-`, `_`, and `.`, or surrounding whitespace.',
 			recommended: 'unopinionated',
 		},
 		messages,

package/rules/no-decimal-file-modes.js

@@ -8,8 +8,8 @@ import {getKeyWords} from './utils/index.js';
 const MESSAGE_ID_ERROR = 'no-decimal-file-modes/error';
 const MESSAGE_ID_SUGGESTION = 'no-decimal-file-modes/suggestion';
 const messages = {
-	[MESSAGE_ID_ERROR]: '`{{number}}` is a decimal number, so this file mode is `{{octal}}`. A file mode is octal, as in `0o{{number}}`.',
-	[MESSAGE_ID_SUGGESTION]: 'Write it as `0o{{number}}`.',
+	[MESSAGE_ID_ERROR]: '`{{number}}` is a decimal number, so this file mode is `{{octal}}`. A file mode is octal, as in `0o{{digits}}`.',
+	[MESSAGE_ID_SUGGESTION]: 'Write it as `0o{{digits}}`.',
 };
 
 /*
@@ -53,10 +53,12 @@ const create = context => {
 		}
 
 		const number = sourceCode.getText(value);
+		// The spec permits `_` between digits, so the digits alone decide what the number is.
+		const digits = number.replaceAll('_', '');
 		const decimal = Number(value.value);
 
 		// The digits look octal, and the value makes no sense as a mode, but the same digits read as octal do.
-		if (!OCTAL_DIGITS.test(number) || isSensibleMode(decimal) || !isSensibleMode(Number.parseInt(number, 8))) {
+		if (!OCTAL_DIGITS.test(digits) || isSensibleMode(decimal) || !isSensibleMode(Number.parseInt(digits, 8))) {
 			return;
 		}
 
@@ -66,12 +68,13 @@ const create = context => {
 			data: {
 				number,
 				octal: `0o${decimal.toString(8)}`,
+				digits,
 			},
 			suggest: [
 				{
 					messageId: MESSAGE_ID_SUGGESTION,
-					data: {number},
-					fix: fixer => fixer.replaceText(value, `0o${number}`),
+					data: {digits},
+					fix: fixer => fixer.replaceText(value, `0o${digits}`),
 				},
 			],
 		};

package/rules/no-dotted-key-collisions.js

@@ -0,0 +1,66 @@
+import {escapeInvisibleCharacters} from './utils/index.js';
+
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'no-dotted-key-collisions';
+const messages = {
+	[MESSAGE_ID]: '`{{key}}` is a key of its own, not `{{rest}}` in the object `{{object}}`, because SOML does not split keys at `.`. Move it into `{{object}}`.',
+};
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('Object', function * (node) {
+		// Only a sibling that is an object shows that the author nests with braces, and then expects `'a.b'` to go into `a`, as in TOML. A flat map of dotted names, such as Spark or log4j settings, or a host next to its domain, has no such object.
+		const objectKeys = new Set(node.members
+			.filter(member => member.value.type === 'Object')
+			.map(member => member.key.value));
+
+		for (const {key, value} of node.members) {
+			const dotIndex = key.value.indexOf('.');
+
+			// A key that starts with `.` names a file, such as `'.eslintrc'`, not a path. A key whose value is an object is more likely a name in a map of objects, such as the logger `'uvicorn.error'` next to `uvicorn`, or the host `'bastion.internal'` next to `bastion`.
+			if (dotIndex <= 0 || value.type === 'Object') {
+				continue;
+			}
+
+			const object = key.value.slice(0, dotIndex);
+
+			if (!objectKeys.has(object)) {
+				continue;
+			}
+
+			yield {
+				node: key,
+				messageId: MESSAGE_ID,
+				data: {
+					key: escapeInvisibleCharacters(context.sourceCode.getText(key)),
+					object: escapeInvisibleCharacters(object),
+					rest: escapeInvisibleCharacters(key.value.slice(dotIndex + 1)),
+				},
+			};
+		}
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow quoted keys with a `.` that read as a path into an object next to them.',
+			recommended: true,
+		},
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/no-duplicate-array-items.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. 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),
+					// A block string spans lines, so it is shown as a one-line string with the same value. A bidirectional control is escaped, or it could reorder the message, whichever spelling the string uses.
+					item: escapeInvisibleCharacters(item.block ? 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-escapes-in-literal-strings.js

@@ -0,0 +1,77 @@
+import {parse} from 'soml-lang';
+import {canBeLiteral, getMeantEscape, toEscapedString} from './utils/index.js';
+
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID_ERROR = 'no-escapes-in-literal-strings/error';
+const MESSAGE_ID_SUGGESTION = 'no-escapes-in-literal-strings/suggestion';
+const messages = {
+	[MESSAGE_ID_ERROR]: 'A literal string, `\'…\'`, has no escapes, so `{{escape}}` is a backslash and `{{rest}}`. Use a `"…"` string for escapes.',
+	[MESSAGE_ID_SUGGESTION]: 'Write it as `{{replacement}}`.',
+};
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('String', node => {
+		if (node.style !== 'literal' || node.block) {
+			return;
+		}
+
+		const escape = getMeantEscape(node.value);
+
+		if (escape === undefined) {
+			return;
+		}
+
+		// Every backslash starts an escape and the value has no `"`, so the same text in `"…"` is a valid string, unless an escape names a character that SOML cannot hold, such as `\u{d}`.
+		let value;
+		try {
+			[value] = parse(`["${node.value}"]`);
+		} catch {
+			return;
+		}
+
+		// A literal string only when it would not be reported again, by this rule or by `no-doubled-backslashes-in-literal-strings`, as in `prefer-literal-strings`.
+		const replacement = canBeLiteral(value) ? `'${value}'` : toEscapedString(value);
+
+		return {
+			node,
+			messageId: MESSAGE_ID_ERROR,
+			data: {
+				escape,
+				rest: escape.slice(1),
+			},
+			suggest: [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					data: {replacement},
+					fix: fixer => fixer.replaceText(node, replacement),
+				},
+			],
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow escapes in literal strings, such as `\'Line one\\nLine two\'`.',
+			recommended: true,
+		},
+		hasSuggestions: true,
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/no-escapes-in-paths.js

@@ -1,3 +1,4 @@
+import {parse} from 'soml-lang';
 import {canBeLiteral, toEscapedString} from './utils/index.js';
 
 /**
@@ -17,11 +18,8 @@ A Windows drive, such as `C:\`, at the start of the string, where a path value s
 */
 const DRIVE = /^[A-Z]:\\/v;
 const ESCAPE = /\\(?:u\{(?<codePoint>[\da-f]+)\}|(?<character>.))/gv;
+// Only these short escapes can be mistaken for path separators; other escapes keep their meaning.
 const MEANINGS = {n: 'a line break', t: 'a tab'};
-// What the author meant by each short escape: `\n` and `\t` are a backslash and a letter, as in the path, and the others mean what they say.
-const MEANT = {
-	'\\': '\\', '"': '"', n: String.raw`\n`, t: String.raw`\t`,
-};
 
 /**
 @param {SomlContext} context
@@ -47,8 +45,9 @@ const create = context => {
 			return;
 		}
 
-		// What the author meant.
-		const value = content.replaceAll(ESCAPE, (escape, codePoint, character) => codePoint === undefined ? MEANT[character] : String.fromCodePoint(Number.parseInt(codePoint, 16)));
+		// What the author meant: make `\n` and `\t` literal, and let the parser decode every other escape. This cannot throw, because the string already parsed, so every escape in it is valid, and `\\n` and `\\t` are valid too.
+		const corrected = content.replaceAll(ESCAPE, (escape, codePoint, character) => Object.hasOwn(MEANINGS, character) ? `\\${escape}` : escape);
+		const [value] = parse(`["${corrected}"]`);
 		const replacement = canBeLiteral(value) ? `'${value}'` : toEscapedString(value);
 		const {character} = mistake.groups;
 		const suggestions = [];

package/rules/no-invisible-characters.js

@@ -20,6 +20,11 @@ const messages = {
 	[MESSAGE_ID_COMMENT]: 'The character U+{{codePoint}} is invisible or looks like a space. Remove it.',
 };
 
+/*
+In a single-line string or a quoted key, a tab also looks like spaces. In a block string and a comment, a tab is allowed, because it indents.
+*/
+const singleLineCharacters = new RegExp(String.raw`${invisibleCharacters.source}|\t`, 'gv');
+
 /**
 @param {SomlContext} context
 */
@@ -43,13 +48,14 @@ const create = context => {
 			messageId = MESSAGE_ID_COMMENT;
 		}
 
+		const characters = isComment(node) || node.block ? invisibleCharacters : singleLineCharacters;
 		let isFirst = true;
 
-		for (const match of sourceCode.getText(node).matchAll(invisibleCharacters)) {
+		for (const match of sourceCode.getText(node).matchAll(characters)) {
 			const [character] = match;
 			const start = nodeStart + match.index;
 			const end = start + character.length;
-			const escape = toUnicodeEscape(character);
+			const escape = character === '\t' ? String.raw`\t` : toUnicodeEscape(character);
 			let fix;
 
 			if (isEscaped) {

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

@@ -11,41 +11,56 @@ const messages = {
 };
 
 const QUOTE_RUNS = {'\'': /'+/gv, '"': /"+/gv};
-// An odd number of backslashes at the end, so the character after them is escaped.
-const ESCAPING_BACKSLASHES = /(?:^|[^\\])(?:\\\\)*\\$/v;
 
 /*
-Whether a run of quotes at `index` closes a quote that the line opened, as in `Say '''hi'''`, because an odd number of runs of the same length come before it.
+The runs of the delimiter's quote character on the line, each with its index, its length, and where it ends. In a `"""` block, `\"` is an escaped quote, so it is not part of the run.
 */
-function isClosingQuote(line, index, delimiter) {
-	const runs = line.slice(0, index).match(QUOTE_RUNS[delimiter[0]]) ?? [];
-	return runs.filter(run => run.length === delimiter.length).length % 2 === 1;
+function getQuoteRuns(line, quote, isEscaped) {
+	return line.matchAll(QUOTE_RUNS[quote]).map(match => {
+		let backslashCount = 0;
+		if (isEscaped) {
+			for (let index = match.index - 1; line[index] === '\\'; index--) {
+				backslashCount++;
+			}
+		}
+
+		// An odd number of backslashes immediately before a quote means it is escaped.
+		const isFirstQuoteEscaped = backslashCount % 2 === 1;
+
+		return {
+			index: match.index + (isFirstQuoteEscaped ? 1 : 0),
+			length: match[0].length - (isFirstQuoteEscaped ? 1 : 0),
+			end: match.index + match[0].length,
+		};
+	}).toArray();
 }
 
 /*
-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.
+Whether the run at `runIndex` closes a quote that the line opened, as in `Say '''hi'''`, because an odd number of runs of the same length come before it.
 */
-const AFTER_DELIMITER = /[\t ]*(?:[,\]\}][\t ]*)*(?:(?:#|\/\*).*)?$/vy;
+function isClosingQuote(runs, runIndex, delimiterLength) {
+	return runs.slice(0, runIndex).filter(run => run.length === delimiterLength).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. The `s` flag lets the comment hold U+2028 or U+2029, which do not end a SOML line.
+*/
+const AFTER_DELIMITER = /[\t ]*(?:[,\]\}][\t ]*)*(?:(?:#|\/\*).*)?$/svy;
 
 /*
 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;
+	const runs = getQuoteRuns(line, delimiter[0], isEscaped);
+
+	for (const [runIndex, {index, length, end}] of runs.entries()) {
 		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;
+		return index > 0 && length === delimiter.length && !isClosingQuote(runs, runIndex, delimiter.length) ? index : undefined;
 	}
 }
 

package/rules/no-quoted-values-in-arrays.js

@@ -0,0 +1,120 @@
+import {parseTree} from 'soml-lang';
+
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID_ERROR = 'no-quoted-values-in-arrays/error';
+const MESSAGE_ID_SUGGESTION = 'no-quoted-values-in-arrays/suggestion';
+const messages = {
+	[MESSAGE_ID_ERROR]: '`{{string}}` is a string, but this array holds {{type}}.',
+	[MESSAGE_ID_SUGGESTION]: 'Write it as `{{value}}`.',
+};
+
+/*
+The types a string can spell. A boolean or `null` in quotes is for `no-quoted-keywords`. A float in quotes is not checked, because it is most often a version, as in `[1.21, 1.22, '1.23']`, where the floats are the mistake.
+*/
+const TYPES = new Map([
+	['Integer', 'ints'],
+	['Instant', 'instants'],
+	['Duration', 'durations'],
+]);
+
+/**
+The type of the one value that `text` is the exact spelling of, such as `'Integer'` for `443` and `'Duration'` for `2s`, or `undefined` when it is not one value.
+
+@param {string} text
+@returns {string | undefined}
+*/
+function getSpelledType(text) {
+	let element;
+	try {
+		[element] = parseTree(`[${text}]`).body.elements;
+	} catch {
+		return;
+	}
+
+	if (element === undefined) {
+		return;
+	}
+
+	// eslint-disable-next-line internal/no-restricted-property-access -- A node of another document, not of this file.
+	const [start, end] = element.range;
+
+	// The value must be all of the text, so whitespace, a comment, or a second item around it does not count.
+	if (start === 1 && end === text.length + 1) {
+		return element.type;
+	}
+}
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('Array', function * (node) {
+		const strings = [];
+		const typed = [];
+
+		// `null` is the missing value in a list of any type, so it does not count.
+		for (const element of node.elements) {
+			if (element.type === 'String') {
+				strings.push(element);
+			} else if (element.type !== 'Null') {
+				typed.push(element);
+			}
+		}
+
+		const type = typed[0]?.type;
+
+		// Each string is reported only when the array would hold one type without quotes, so an array with other text, such as `[80, 443, 'auto', '8080']`, is not. The quoted items must also be no more than the others, or the others are more likely the mistake.
+		if (
+			!TYPES.has(type)
+			|| strings.length === 0
+			|| strings.length > typed.length
+			|| typed.some(element => element.type !== type)
+			|| strings.some(string => string.block || getSpelledType(string.value) !== type)
+		) {
+			return;
+		}
+
+		for (const string of strings) {
+			const {value} = string;
+
+			yield {
+				node: string,
+				messageId: MESSAGE_ID_ERROR,
+				data: {
+					string: context.sourceCode.getText(string),
+					type: TYPES.get(type),
+				},
+				suggest: [
+					{
+						messageId: MESSAGE_ID_SUGGESTION,
+						data: {value},
+						fix: fixer => fixer.replaceText(string, value),
+					},
+				],
+			};
+		}
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow quoted values in an array of that type, such as `\'443\'` in `[80, \'443\']`.',
+			recommended: true,
+		},
+		hasSuggestions: true,
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/no-sizes-as-durations.js

@@ -1,4 +1,4 @@
-import {getKeyWords} from './utils/index.js';
+import {escapeInvisibleCharacters, getKeyWords} from './utils/index.js';
 
 /**
 @import {SomlContext} from './rule/soml-context.js';
@@ -86,7 +86,7 @@ const create = context => {
 			messageId: MESSAGE_ID_ERROR,
 			data: {
 				duration,
-				key: context.sourceCode.getText(key),
+				key: escapeInvisibleCharacters(context.sourceCode.getText(key)),
 			},
 			suggest: [
 				{

package/rules/no-surrounding-whitespace-in-keys.js

@@ -0,0 +1,53 @@
+import {escapeInvisibleCharacters, trimWhitespace} from './utils/index.js';
+
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'no-surrounding-whitespace-in-keys';
+const messages = {
+	[MESSAGE_ID]: 'The whitespace at the start or end of `{{key}}` is part of the key, so a program that reads `{{trimmed}}` does not find it.',
+};
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	context.on('Key', node => {
+		const trimmed = trimWhitespace(node.value);
+
+		// A key of only whitespace is for `no-empty-keys`.
+		if (trimmed === '' || trimmed === node.value) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {
+				// The source text shows the quotes, so the whitespace is visible, and an invisible character is escaped.
+				key: escapeInvisibleCharacters(context.sourceCode.getText(node)),
+				trimmed: escapeInvisibleCharacters(trimmed),
+			},
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow whitespace at the start and end of keys.',
+			recommended: true,
+		},
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/prefer-block-strings.js

@@ -0,0 +1,129 @@
+import {
+	escapeInvisibleCharacters,
+	getMeantEscape,
+	hasDoubledBackslashes,
+	hasInvisibleCharacter,
+	trimEnd,
+} from './utils/index.js';
+
+/**
+@import {SomlContext} from './rule/soml-context.js';
+@import {SomlRule} from './rule/to-eslint-rule.js';
+*/
+
+const MESSAGE_ID = 'prefer-block-strings';
+const messages = {
+	[MESSAGE_ID]: 'A string of three lines or more is easier to read as a block string.',
+};
+
+const MINIMUM_LINES = 3;
+
+const hasTrailingWhitespace = line => trimEnd(line, '\t ') !== line;
+
+/**
+Write the lines of a `"""` block string. Every escape that `"…"` has works in it, so the line breaks at the edges, which a block string would drop, and the whitespace at the end of a line, which an editor can remove, are written as escapes.
+
+@param {string[]} lines
+@param {number} leadingCount The number of line breaks at the start of the value.
+@param {number} trailingCount The number of line breaks at the end of the value.
+@returns {string[]}
+*/
+function getEscapedLines(lines, leadingCount, trailingCount) {
+	const escapedLines = lines.map(line => {
+		const text = trimEnd(line, '\t ');
+		const whitespace = line.slice(text.length).replaceAll(' ', String.raw`\u{20}`).replaceAll('\t', String.raw`\t`);
+		return escapeInvisibleCharacters(text.replaceAll('\\', '\\\\')) + whitespace;
+	});
+
+	escapedLines[0] = String.raw`\n`.repeat(leadingCount) + escapedLines[0];
+	escapedLines[escapedLines.length - 1] += String.raw`\n`.repeat(trailingCount);
+
+	return escapedLines;
+}
+
+/**
+The block string for `value`, with its lines at `indent`, or `undefined` when there is none. A `'''` block string is used when it holds the value as it is, as `prefer-literal-strings` asks, and a `"""` block string otherwise.
+
+@param {string} value
+@param {string} indent
+@returns {string | undefined}
+*/
+function getBlockString(value, indent) {
+	const withoutTrailing = trimEnd(value, '\n');
+	const text = withoutTrailing.replace(/^\n+/v, '');
+	const leadingCount = withoutTrailing.length - text.length;
+	const trailingCount = value.length - withoutTrailing.length;
+	const lines = text.split('\n');
+
+	if (lines.length < MINIMUM_LINES) {
+		return;
+	}
+
+	// A line break at the start or end, and whitespace at the end of a line, would be lost or invisible in `'''`, which has no escapes. A `'''` in the text could end it. A doubled backslash reads as a mistake, which `no-doubled-backslashes-in-literal-strings` reports, and so does a backslash that `getMeantEscape()` reads as an escape, such as `\u{41}`.
+	const isLiteral = leadingCount === 0
+		&& trailingCount === 0
+		&& !text.includes('\'\'\'')
+		&& !hasInvisibleCharacter(text)
+		&& !hasDoubledBackslashes(text)
+		&& getMeantEscape(text) === undefined
+		&& lines.every(line => !hasTrailingWhitespace(line));
+
+	if (!isLiteral && text.includes('"""')) {
+		return;
+	}
+
+	const delimiter = isLiteral ? '\'\'\'' : '"""';
+	const contentLines = isLiteral ? lines : getEscapedLines(lines, leadingCount, trailingCount);
+
+	// An empty line needs no indentation.
+	const content = contentLines.map(line => line === '' ? '' : indent + line).join('\n');
+	return `${delimiter}\n${content}\n${indent}${delimiter}`;
+}
+
+/**
+@param {SomlContext} context
+*/
+const create = context => {
+	const {sourceCode} = context;
+
+	context.on('String', node => {
+		if (node.style !== 'escaped' || node.block || !node.value.includes('\n')) {
+			return;
+		}
+
+		// A value that starts its own line is already where the formatter puts a block string. One after a key or another value goes one level deeper. The `format` rule then moves the opening delimiter to the next line, as the formatter does.
+		const {start} = sourceCode.getLoc(node);
+		const [lineIndent] = /^[\t ]*/v.exec(sourceCode.lines[start.line - 1]);
+		const indent = start.column === lineIndent.length ? lineIndent : `${lineIndent}\t`;
+		const blockString = getBlockString(node.value, indent);
+
+		if (blockString === undefined) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			fix: fixer => fixer.replaceText(node, blockString),
+		};
+	});
+};
+
+/**
+@type {SomlRule}
+*/
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer block strings for strings of three lines or more.',
+			recommended: true,
+		},
+		fixable: 'code',
+		messages,
+		languages: ['soml/soml'],
+	},
+};
+
+export default config;

package/rules/prefer-literal-strings.js

@@ -1,4 +1,4 @@
-import {canBeLiteral, hasDoubledBackslashes, hasInvisibleCharacter} from './utils/index.js';
+import {canBeLiteral, hasInvisibleCharacter} from './utils/index.js';
 
 /**
 @import {SomlContext} from './rule/soml-context.js';
@@ -29,8 +29,8 @@ function getLiteral(node, text) {
 		return delimiter + text.slice(delimiter.length, -delimiter.length) + delimiter;
 	}
 
-	// A value such as `^\\d+$` reads as a mistake in a literal string, which `no-doubled-backslashes-in-literal-strings` reports.
-	if (canBeLiteral(node.value) && !hasDoubledBackslashes(node.value)) {
+	// A value such as `^\\d+$` or `Done.\n` reads as a mistake in a literal string, so `canBeLiteral()` keeps it escaped.
+	if (canBeLiteral(node.value)) {
 		return `'${node.value}'`;
 	}
 }

package/rules/sort-keys.js

@@ -1,5 +1,5 @@
 import {compareKeys} from 'soml-lang';
-import {isDisabledAnywhere, reorderMembers} from './utils/index.js';
+import {escapeInvisibleCharacters, isDisabledAnywhere, reorderMembers} from './utils/index.js';
 
 /**
 @import {SomlContext} from './rule/soml-context.js';
@@ -147,8 +147,8 @@ const create = context => {
 					node: member.key,
 					messageId: MESSAGE_ID,
 					data: {
-						thisName: sourceCode.getText(member.key),
-						previousName: sourceCode.getText(previous.key),
+						thisName: escapeInvisibleCharacters(sourceCode.getText(member.key)),
+						previousName: escapeInvisibleCharacters(sourceCode.getText(previous.key)),
 						direction: direction === 'asc' ? 'ascending' : 'descending',
 						sensitivity: caseSensitive ? 'sensitive' : 'insensitive',
 						sortName: natural ? 'natural' : 'code point',

package/rules/spaced-comment.js

@@ -18,9 +18,9 @@ const BLOCK_START = /^\**(?=[^\s*])/v;
 const BLOCK_END = /(?<=[^\s*])\**$/v;
 
 /*
-A line comment that is only a hex color, as in `#ff0000`, is almost always a color meant as an array item, which `#` turned into a comment. Adding a space would hide that mistake, so the rule leaves it, also with whitespace or another comment after it, as in `#ff0000 # red`.
+A line comment that is only a hex color, as in `#ff0000`, is almost always a color meant as an array item, which `#` turned into a comment. Adding a space would hide that mistake, so the rule leaves it, also with a comma, whitespace, or another comment after it, as in `#ff0000,` or `#ff0000 # red`. The `s` flag lets that comment hold U+2028 or U+2029, which do not end a SOML line.
 */
-const HEX_COLOR = /^(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8}),?(?:[\t ]+(?:#|\/\*).*|[\t ]*)$/iv;
+const HEX_COLOR = /^(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})(?:[\t ]*,)?(?:[\t ]*$|[\t ]+(?:#|\/\*).*$)/isv;
 
 /**
 @param {SomlContext} context

package/rules/utils/escape-string.js

@@ -1,4 +1,6 @@
 import {invisibleCharacters, hasInvisibleCharacter} from './invisible-characters.js';
+import hasDoubledBackslashes from './has-doubled-backslashes.js';
+import getMeantEscape from './get-meant-escape.js';
 
 const NOT_LITERAL = /[\p{Control}']/v;
 
@@ -13,13 +15,16 @@ export function toUnicodeEscape(character) {
 }
 
 /**
-Write every invisible character in `text` as a `\u{…}` escape, such as for a decoded value in a message, where a control character could change the terminal and a bidirectional control could reorder the text.
+Write line feeds and tabs in `text` as short escapes and every other invisible character as a `\u{…}` escape, such as for a decoded value in a message, where a control character could change the terminal and a bidirectional control could reorder the text.
 
 @param {string} text
 @returns {string}
 */
 export function escapeInvisibleCharacters(text) {
-	return text.replaceAll(invisibleCharacters, character => toUnicodeEscape(character));
+	return text
+		.replaceAll(invisibleCharacters, character => toUnicodeEscape(character))
+		.replaceAll('\n', String.raw`\n`)
+		.replaceAll('\t', String.raw`\t`);
 }
 
 /**
@@ -39,11 +44,14 @@ export function toEscapedString(value) {
 }
 
 /**
-Whether a value should be written as a `'...'` string: it has no `'`, which would end it, and no line feed, tab, or other control character, which `'...'` cannot hold or which are invisible in it. A value with an invisible character also stays escaped, as `no-invisible-characters` asks. This is stricter than canonical form, which writes C1 controls and other invisible characters in `'...'`.
+Whether a value should be written as a `'...'` string: it has no `'`, which would end it, and no line feed, tab, or other control character, which `'...'` cannot hold or which are invisible in it. A value with an invisible character also stays escaped, as `no-invisible-characters` asks. So does a value that reads as a mistake in `'...'`: one such as `^\\d+$`, which `no-doubled-backslashes-in-literal-strings` reports, and one such as `Done.\n`, with a backslash and `n`, which `no-escapes-in-literal-strings` reports. This is stricter than canonical form, which writes C1 controls and other invisible characters in `'...'`.
 
 @param {string} value
 @returns {boolean}
 */
 export function canBeLiteral(value) {
-	return !NOT_LITERAL.test(value) && !hasInvisibleCharacter(value);
+	return !NOT_LITERAL.test(value)
+		&& !hasInvisibleCharacter(value)
+		&& !hasDoubledBackslashes(value)
+		&& getMeantEscape(value) === undefined;
 }

package/rules/utils/get-meant-escape.js

@@ -0,0 +1,46 @@
+/*
+A backslash and what follows it, as a `"…"` string reads them. A `\u{…}` in another spelling, such as `\u{E9}` or `\u0041`, is not a SOML escape, so it goes to `other`, and so does a backslash at the end.
+*/
+const BACKSLASH = /\\(?:(?<escape>[\\nt]|u\{(?:0|[1-9a-f][\da-f]{0,5})\})|(?<other>.?))/gsv;
+
+/*
+A Windows path, which starts with a drive, as in `C:\`, a network share, as in `\\server`, or a relative folder, as in `.\` and `..\`.
+*/
+const PATH = /^(?:[A-Za-z]:\\|\\\\|\.\.?\\)/v;
+const WHITESPACE = /[\t ]/v;
+const NAME_START = /[\p{Letter}\p{Number}]/v;
+
+/**
+The first escape in a value that was likely meant as one, such as `\n` in `Line one\nLine two`, or `undefined` when there is none. In a literal string, `'…'`, an escape is a backslash and the characters after it, as it is in TOML and in a shell, but in JavaScript and Python, `'…'` reads escapes.
+
+A value is only checked when every backslash in it starts a SOML escape, so a regular expression such as `^\d+\n$`, which has `\d`, is not. A Windows path is not checked either, and neither is a value with a `"`, because it is code with strings in it, such as JSON text or a shell command with `printf "%s\n"`, which keeps its escapes for the program that runs it.
+
+A `\u{…}` escape is always likely meant. A `\n` or `\t` is when the value has a space or a tab, as text does, or when no letter or digit follows it, as at the end of `Done.\n`. A `\n` or `\t` before a name without whitespace in the value, as in `src\test`, is more likely a path.
+
+@param {string} value
+@returns {string | undefined}
+*/
+export default function getMeantEscape(value) {
+	if (value.includes('"') || PATH.test(value)) {
+		return;
+	}
+
+	const backslashes = value.matchAll(BACKSLASH).toArray();
+
+	if (backslashes.some(({groups}) => groups.escape === undefined)) {
+		return;
+	}
+
+	const hasWhitespace = WHITESPACE.test(value);
+	// Only the character after the escape is read, so a value with many escapes takes linear time.
+	const isBeforeName = index => {
+		const codePoint = value.codePointAt(index);
+		return codePoint !== undefined && NAME_START.test(String.fromCodePoint(codePoint));
+	};
+
+	const isMeant = ({0: escape, index}) => escape.startsWith(String.raw`\u`)
+		|| hasWhitespace
+		|| !isBeforeName(index + escape.length);
+
+	return backslashes.find(match => match[0] !== '\\\\' && isMeant(match))?.[0];
+}

package/rules/utils/index.js

@@ -11,5 +11,6 @@ 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 getMeantEscape} from './get-meant-escape.js';
 export {default as getKeyWords} from './get-key-words.js';
 export {default as isDisabledAnywhere} from './is-disabled-anywhere.js';

package/rules/utils/reorder-members.js

@@ -26,7 +26,7 @@ export function hasAdjacentComment(context, node) {
 /**
 A fix that puts `members` in the order of `ordered`, by replacing the text of each member with the text of the member that belongs there. The separators stay where they are. Object members have no order in SOML, so this keeps the value.
 
-It aborts when a comment is next to any of the members, because the comment would end up next to the wrong one.
+It aborts when a comment is next to any member or inside a moved member, so comments stay where they are.
 
 @param {SomlContext} context
 @param {readonly MemberNode[]} members The members in source order.
@@ -39,9 +39,15 @@ export function reorderMembers(context, members, ordered) {
 		}
 
 		for (const [index, member] of members.entries()) {
-			if (ordered[index] !== member) {
-				yield fixer.replaceText(member, context.sourceCode.getText(ordered[index]));
+			if (ordered[index] === member) {
+				continue;
 			}
+
+			if (context.sourceCode.getTokens(member, {includeComments: true}).some(token => isComment(token))) {
+				abort();
+			}
+
+			yield fixer.replaceText(member, context.sourceCode.getText(ordered[index]));
 		}
 	};
 }