fix: Mark adding words to custom dictionary experimental

packages/cspell-eslint-plugin/src/_auto_generated_/options.schema.json

@@ -1,7 +1,30 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "additionalProperties": false,
-  "definitions": {},
+  "definitions": {
+    "CustomWordListFile": {
+      "additionalProperties": false,
+      "properties": {
+        "addWords": {
+          "description": "**Experimental**: Provide a fix option to add words to the file.\n\nNote: this does not yet work perfectly.",
+          "type": "boolean"
+        },
+        "path": {
+          "$ref": "#/definitions/CustomWordListFilePath",
+          "description": "Path to word list file. File format: 1 word per line"
+        }
+      },
+      "required": [
+        "path",
+        "addWords"
+      ],
+      "type": "object"
+    },
+    "CustomWordListFilePath": {
+      "description": "Specify a path to a custom word list file",
+      "type": "string"
+    }
+  },
   "properties": {
     "checkComments": {
       "default": true,
@@ -24,8 +47,15 @@
       "type": "boolean"
     },
     "customWordListFile": {
-      "description": "**Experimental**: Specify a path to a custom word list file. A utf-8 text file with one word per line. This file is used to present the option to add words.",
-      "type": "string"
+      "anyOf": [
+        {
+          "$ref": "#/definitions/CustomWordListFilePath"
+        },
+        {
+          "$ref": "#/definitions/CustomWordListFile"
+        }
+      ],
+      "description": "Specify a path to a custom word list file"
     },
     "debugMode": {
       "default": false,

packages/cspell-eslint-plugin/src/cspell-eslint-plugin.ts

@@ -15,7 +15,7 @@ import type { Comment, Identifier, ImportSpecifier, Literal, Node, TemplateEleme
 import * as path from 'path';
 import { format } from 'util';
 import { addWordToCustomWordList } from './customWordList';
-import { normalizeOptions, Options } from './options';
+import { CustomWordListFile, normalizeOptions, Options } from './options';
 import optionsSchema from './_auto_generated_/options.schema.json';
 
 const schema = optionsSchema as unknown as Rule.RuleMetaData['schema'];
@@ -210,9 +210,11 @@ function create(context: Rule.RuleContext): Rule.RuleListener {
         }
 
         function createAddWordToDictionaryFix(word: string): Rule.SuggestionReportDescriptor | undefined {
-            if (!options.customWordListFile) return undefined;
+            if (!isCustomWordListFile(options.customWordListFile) || !options.customWordListFile.addWords) {
+                return undefined;
+            }
 
-            const dictFile = path.resolve(context.getCwd(), options.customWordListFile);
+            const dictFile = path.resolve(context.getCwd(), options.customWordListFile.path);
 
             const data = { word, dictionary: path.basename(dictFile) };
             const messageId: MessageIds = 'addWordToDictionary';
@@ -434,9 +436,11 @@ function getDocValidator(context: Rule.RuleContext): DocumentValidator {
 }
 
 function calcInitialSettings(options: Options, cwd: string): CSpellSettings {
-    if (!options.customWordListFile) return defaultSettings;
+    const { customWordListFile } = options;
+    if (!customWordListFile) return defaultSettings;
 
-    const dictFile = path.resolve(cwd, options.customWordListFile);
+    const filePath = isCustomWordListFile(customWordListFile) ? customWordListFile.path : customWordListFile;
+    const dictFile = path.resolve(cwd, filePath);
 
     const settings: CSpellSettings = {
         ...defaultSettings,
@@ -481,3 +485,7 @@ class WrapFix implements Rule.Fix {
         return this.fix.text;
     }
 }
+
+function isCustomWordListFile(value: string | CustomWordListFile | undefined): value is CustomWordListFile {
+    return !!value && typeof value === 'object';
+}

packages/cspell-eslint-plugin/src/options.ts

@@ -58,10 +58,28 @@ export interface Check {
      */
     checkComments?: boolean;
     /**
-     * **Experimental**: Specify a path to a custom word list file. A utf-8 text file with one word per line.
-     * This file is used to present the option to add words.
+     * Specify a path to a custom word list file
      */
-    customWordListFile?: string | undefined;
+    customWordListFile?: CustomWordListFilePath | CustomWordListFile | undefined;
+}
+
+/**
+ * Specify a path to a custom word list file
+ */
+export type CustomWordListFilePath = string;
+
+export interface CustomWordListFile {
+    /**
+     * Path to word list file.
+     * File format: 1 word per line
+     */
+    path: CustomWordListFilePath;
+    /**
+     * **Experimental**: Provide a fix option to add words to the file.
+     *
+     * Note: this does not yet work perfectly.
+     */
+    addWords: boolean;
 }
 
 export const defaultCheckOptions: Required<Check> = {