eslint-soml 0.0.3 → 0.0.5

package/index.d.ts

@@ -1,4 +1,28 @@
 import type {ESLint, Linter} from 'eslint';
+import type {LanguageOptions, RuleVisitor} from '@eslint/core';
+import type {
+	CustomRuleDefinitionType,
+	CustomRuleTypeDefinitions,
+	CustomRuleVisitorWithExit,
+	TextSourceCodeBase,
+} from '@eslint/plugin-kit';
+import type {
+	Node,
+	DocumentNode,
+	ObjectNode,
+	MemberNode,
+	ArrayNode,
+	KeyNode,
+	StringNode,
+	IntegerNode,
+	FloatNode,
+	BooleanNode,
+	NullNode,
+	InstantNode,
+	DurationNode,
+	Token,
+	Comment,
+} from 'soml-lang';
 
 export type {
 	Node,
@@ -22,6 +46,191 @@ 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. 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
+```
+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 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.
+	*/
+	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, parent: undefined): 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/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

@@ -13,6 +13,15 @@ import {visitorKeys} from 'soml-lang';
 
 const commentParser = new ConfigCommentParser();
 const INLINE_CONFIG = /^\s*eslint(?:-enable|-disable(?:(?:-next)?-line)?)?(?:\s|$)/v;
+const RULE_CONFIG = /^\s*eslint(?:\s|$)/v;
+// What separates a directive from its justification, as ESLint splits it.
+const JUSTIFICATION = /\s-{2,}\s/v;
+
+/*
+Whether a comment is a directive. A `#` comment is the usual comment style, so one that starts with `eslint` in prose, as in `# eslint version to install`, is not a rule configuration. A rule configuration always has a `:`, so a `#` comment without one before its justification is not a directive.
+*/
+const isInlineConfig = comment => INLINE_CONFIG.test(comment.value)
+	&& !(comment.type === 'Line' && RULE_CONFIG.test(comment.value) && !comment.value.split(JUSTIFICATION, 1)[0].includes(':'));
 
 const isComment = item => item.type === 'Line' || item.type === 'Block';
 
@@ -58,10 +67,20 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 	*/
 	#inlineConfigComments;
 	/**
+	Where each line starts, found once, when it is first needed.
+
+	@type {number[] | undefined}
+	*/
+	#lineStarts;
+	/**
 	@type {DocumentNode}
 	*/
 	ast;
 	visitorKeys = visitorKeys;
+	/**
+	Marks the source code as SOML, so a rule that works on several languages can tell, as `eslint-plugin-yml` and `eslint-plugin-toml` do with `isYAML` and `isTOML`.
+	*/
+	parserServices = {isSOML: true};
 
 	/**
 	@param {{text: string, ast: DocumentNode}} options
@@ -113,6 +132,86 @@ 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.
+
+	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}).`);
+		}
+
+		// The last line that starts at or before `index`.
+		const lineStarts = this.#getLineStarts();
+		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]};
+	}
+
+	/**
+	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>}
 	*/
@@ -161,7 +260,8 @@ 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[]}
 	*/
@@ -173,7 +273,7 @@ export default class SomlSourceCode extends TextSourceCodeBase {
 	@returns {Comment[]}
 	*/
 	getInlineConfigNodes() {
-		this.#inlineConfigComments ??= this.ast.comments.filter(comment => INLINE_CONFIG.test(comment.value));
+		this.#inlineConfigComments ??= this.ast.comments.filter(comment => isInlineConfig(comment));
 		return this.#inlineConfigComments;
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eslint-soml",
-	"version": "0.0.3",
+	"version": "0.0.5",
 	"description": "ESLint plugin for SOML, a config format for humans",
 	"license": "MIT",
 	"repository": "github:soml-lang/eslint-soml",
@@ -51,22 +51,22 @@
 		"style"
 	],
 	"dependencies": {
+		"@eslint/core": "^1.2.1",
 		"@eslint/plugin-kit": "^0.7.3",
-		"soml-lang": "^0.0.4"
+		"soml-lang": "^0.0.7"
 	},
 	"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",
+		"@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.1",
+		"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

@@ -16,7 +16,7 @@ npm install --save-dev eslint eslint-soml
 
 **Requires Node.js 22.13 or later, ESLint `>=10.4`, [flat config](https://eslint.org/docs/latest/use/configure/configuration-files), and [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c#how-can-i-make-my-typescript-project-output-esm).**
 
-The parser needs `Temporal` for instants and durations, and Node.js 26 and later have it built in. On older versions, linting a file with an instant or a duration fails, unless a [`Temporal` polyfill](https://github.com/fullcalendar/temporal-polyfill) is loaded first. Make `import 'temporal-polyfill/global';` the first import in `eslint.config.js`, before `eslint-soml`.
+The rules of this plugin do not need `Temporal`, so they work on every supported Node.js version, also for files with instants and durations. Only reading the `value` of an `Instant` or `Duration` node needs it, as in your own rule or in a `no-restricted-syntax` selector that matches on `value`, such as `[value=1]`. Node.js 26 and later have `Temporal` built in. On older versions, load a [`Temporal` polyfill](https://github.com/fullcalendar/temporal-polyfill) first: make `import 'temporal-polyfill/global';` the first import in `eslint.config.js`, before `eslint-soml`.
 
 ## Usage
 
@@ -61,7 +61,7 @@ Disable a rule with a comment, in either comment style:
 '404': 'Not found' /* eslint-disable-line soml/prefer-bare-keys */
 ```
 
-The [`reportUnusedDisableDirectives`](https://eslint.org/docs/latest/use/configure/configuration-files#report-unused-disable-directives) and [`reportUnusedInlineConfigs`](https://eslint.org/docs/latest/use/configure/configuration-files#report-unused-inline-configs) linter options work for `.soml` files, and so do the rules of [`@eslint-community/eslint-plugin-eslint-comments`](https://github.com/eslint-community/eslint-plugin-eslint-comments), such as `no-unlimited-disable`.
+The [`reportUnusedDisableDirectives`](https://eslint.org/docs/latest/use/configure/configuration-files#report-unused-disable-directives) and [`reportUnusedInlineConfigs`](https://eslint.org/docs/latest/use/configure/configuration-files#report-unused-inline-configs) linter options work for `.soml` files, and so do the rules of [`@eslint-community/eslint-plugin-eslint-comments`](https://github.com/eslint-community/eslint-plugin-eslint-comments), such as `no-unlimited-disable`. Those rules follow JavaScript, where a line comment holds only `eslint-disable-line` and `eslint-disable-next-line`, so some of them, such as `no-unlimited-disable` and `no-use`, do not check `# eslint-disable` and `# eslint-enable`. Write those as `/* … */` comments to have them checked.
 
 ESLint's [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax) rule works too. For example, to disallow a key named `password`:
 
@@ -86,6 +86,86 @@ 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.',
+	},
+],
+```
+
+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:
+
+```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` -->
@@ -97,35 +177,40 @@ export default defineConfig([
 🔧 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 that cannot be stored exactly as written.                       | ✅ ☑️ |    |    |
-| [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 has no 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 -->
 
@@ -201,6 +286,10 @@ In Visual Studio Code, the [ESLint extension](https://marketplace.visualstudio.c
 }
 ```
 
+## Writing rules
+
+See [how to write rules for SOML files](docs/writing-rules.md).
+
 ## Related
 
 - [soml-javascript](https://github.com/soml-lang/soml-javascript) - The reference parser and serializer for SOML

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';