eslint-soml 0.0.4 → 0.0.6

package/index.d.ts

@@ -18,6 +18,7 @@ import type {
 	FloatNode,
 	BooleanNode,
 	NullNode,
+	DateNode,
 	InstantNode,
 	DurationNode,
 	Token,
@@ -37,6 +38,7 @@ export type {
 	FloatNode,
 	BooleanNode,
 	NullNode,
+	DateNode,
 	InstantNode,
 	DurationNode,
 	DurationPart,
@@ -66,7 +68,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 +112,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 +170,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;
@@ -168,6 +180,17 @@ export interface SomlRuleVisitor extends RuleVisitor, CustomRuleVisitorWithExit<
 	Float?(node: FloatNode, parent: ValueParent): void;
 	Boolean?(node: BooleanNode, parent: ValueParent): void;
 	Null?(node: NullNode, parent: ValueParent): void;
+	/**
+	Visits a calendar date without needing Temporal to read its components.
+
+	@example
+	```
+	Date(node) {
+		const year: number = node.year;
+	}
+	```
+	*/
+	Date?(node: DateNode, parent: ValueParent): void;
 	Instant?(node: InstantNode, parent: ValueParent): void;
 	Duration?(node: DurationNode, parent: ValueParent): 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.6",
 	"description": "ESLint plugin for SOML, a config format for humans",
 	"license": "MIT",
 	"repository": "github:soml-lang/eslint-soml",
@@ -53,23 +53,23 @@
 	"dependencies": {
 		"@eslint/core": "^1.2.1",
 		"@eslint/plugin-kit": "^0.7.3",
-		"soml-lang": "^0.0.5"
+		"soml-lang": "^0.0.8"
 	},
 	"devDependencies": {
 		"@babel/code-frame": "^8.0.6",
 		"@eslint-community/eslint-utils": "^4.10.1",
-		"@typescript-eslint/types": "^8.71.1",
+		"@typescript-eslint/types": "^8.72.1",
 		"enquirer": "^2.4.1",
-		"eslint": "^10.12.0",
-		"eslint-config-xo": "^5.0.0",
+		"eslint": "^10.14.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.4.2",
 		"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",
+		"npm-run-all2": "^9.0.4",
 		"open-editor": "^6.0.0",
 		"outdent": "^0.8.0",
 		"typescript": "^6.0.3",

package/readme.md

@@ -16,7 +16,7 @@ npm install --save-dev eslint eslint-soml
 
 **Requires Node.js 22.13 or later, ESLint `>=10.4`, [flat config](https://eslint.org/docs/latest/use/configure/configuration-files), and [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c#how-can-i-make-my-typescript-project-output-esm).**
 
-The 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`.
+The rules of this plugin do not need `Temporal`, so they work on every supported Node.js version, also for files with dates, instants, and durations. Only reading the `value` of a `Date`, `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
 
@@ -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(Date, Instant, Duration)',
+		message: 'This program does not support dates, 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 duplicate strings and dates 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;