eslint-soml 0.0.2 → 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,
@@ -7,7 +31,6 @@ export type {
 	MemberNode,
 	ArrayNode,
 	KeyNode,
-	KeySegmentNode,
 	ValueNode,
 	StringNode,
 	IntegerNode,
@@ -23,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,9 +13,40 @@ 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';
 
+/*
+Merges the tokens and the comments, which are each in source order, into one list in source order. A merge takes linear time, where a sort would not.
+*/
+function mergeByStart(tokens, comments) {
+	const items = [];
+	let commentIndex = 0;
+
+	for (const token of tokens) {
+		while (commentIndex < comments.length && comments[commentIndex].range[0] < token.range[0]) {
+			items.push(comments[commentIndex++]);
+		}
+
+		items.push(token);
+	}
+
+	while (commentIndex < comments.length) {
+		items.push(comments[commentIndex++]);
+	}
+
+	return items;
+}
+
 /**
 The source code of a SOML document, which rules get as `context.sourceCode`.
 */
@@ -36,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
@@ -48,7 +89,7 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 		// SOML has no carriage returns, so a line ends only at a line feed.
 		super({text, ast, lineEndingPattern: /\n/v});
 		this.ast = ast;
-		this.#items = [...ast.tokens, ...ast.comments].toSorted((first, second) => first.range[0] - second.range[0]);
+		this.#items = mergeByStart(ast.tokens, ast.comments);
 	}
 
 	/*
@@ -91,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>}
 	*/
@@ -140,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[]}
 	*/
@@ -151,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.2",
+	"version": "0.0.4",
 	"description": "ESLint plugin for SOML, a config format for humans",
 	"license": "MIT",
 	"repository": "github:soml-lang/eslint-soml",
@@ -51,21 +51,20 @@
 		"style"
 	],
 	"dependencies": {
+		"@eslint/core": "^1.2.1",
 		"@eslint/plugin-kit": "^0.7.3",
-		"natural-compare": "^1.4.0",
-		"soml-lang": "^0.0.3"
+		"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

@@ -2,6 +2,8 @@
 
 > ESLint plugin for [SOML](https://github.com/soml-lang/soml), a config format for humans
 
+[`eslint-plugin-unicorn`](https://github.com/sindresorhus/eslint-plugin-unicorn#soml) has more rules that also lint SOML, such as `prefer-https` and `name-replacements`.
+
 [**Propose a new rule ➡**](.github/contributing.md)
 
 *We do not accept pull requests because of too much AI slop.*
@@ -14,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
 
@@ -59,9 +61,9 @@ 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, with the [node types](#writing-rules) of the tree. For example, to disallow a key named `password`:
+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`:
 
 ```js
 import soml from 'eslint-soml';
@@ -75,7 +77,7 @@ export default defineConfig([
 			'no-restricted-syntax': [
 				'error',
 				{
-					selector: 'Member > Key > KeySegment[value="password"]',
+					selector: 'Member > Key[value="password"]',
 					message: 'Read the password from the environment.',
 				},
 			],
@@ -84,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` -->
@@ -109,20 +159,18 @@ 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.                                                        | ✅    | 🔧 |    |
-| [no-numeric-dotted-keys](docs/rules/no-numeric-dotted-keys.md)                                       | Disallow dotted keys that read as one number.                                   | ✅ ☑️ |    | 💡 |
 | [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-scattered-dotted-keys](docs/rules/no-scattered-dotted-keys.md)                                   | Require the dotted keys under one prefix to be next to each other.              | ✅    | 🔧 |    |
 | [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 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/format.js

@@ -1,4 +1,5 @@
 import {formatEdits} from 'soml-lang';
+import {isDisabledAnywhere} from './utils/index.js';
 
 /**
 @import {SomlContext} from './rule/soml-context.js';
@@ -32,6 +33,12 @@ const create = context => {
 		const {text} = sourceCode;
 		const edits = formatEdits(text);
 
+		if (edits.length === 0) {
+			return;
+		}
+
+		const isFixable = !isDisabledAnywhere(context);
+
 		// eslint-disable-next-line internal/no-restricted-property-access -- An edit is not a node.
 		for (const [index, {range, text: inserted}] of edits.entries()) {
 			const [start, end] = range;
@@ -54,8 +61,8 @@ const create = context => {
 					deleted: showInvisibles(deleted),
 					inserted: showInvisibles(inserted),
 				},
-				// Every edit is in one fix, so the formatting is applied at once. Applying only some edits, when a fix from another rule overlaps one of them, could leave a block string half moved. Only the first problem carries the fix, because a copy of every edit in every problem would make the output grow with the file size times the problem count.
-				fix: index === 0
+				// Every edit is in one fix, so the formatting is applied at once. Applying only some edits, when a fix from another rule overlaps one of them, could leave a block string half moved. Only the first problem carries the fix, because a copy of every edit in every problem would make the output grow with the file size times the problem count. There is no fix when a directive turns the rule off anywhere, because the fix would change those lines too.
+				fix: index === 0 && isFixable
 					? function * (fixer) {
 						// eslint-disable-next-line internal/no-restricted-property-access -- An edit is not a node.
 						for (const {range, text} of edits) {

package/rules/index.js

@@ -16,10 +16,8 @@ export {default as 'no-loss-of-precision'} from './no-loss-of-precision.js';
 export {default as 'no-misplaced-block-string-delimiters'} from './no-misplaced-block-string-delimiters.js';
 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-numeric-dotted-keys'} from './no-numeric-dotted-keys.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-scattered-dotted-keys'} from './no-scattered-dotted-keys.js';
 export {default as 'no-sizes-as-durations'} from './no-sizes-as-durations.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';

package/rules/key-name-casing.js

@@ -27,7 +27,7 @@ const create = context => {
 	const pattern = CASES[keyCase];
 	const ignorePatterns = ignore.map(source => new RegExp(source, 'v'));
 
-	context.on('KeySegment', node => {
+	context.on('Key', node => {
 		// A quoted key holds data rather than a name, such as a path or a URL, so it is not checked.
 		if (
 			node.style !== 'bare'

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;
 		}
 	});
 };