docs: document flagWords case-sensitivity behavior

packages/cspell-dictionary/src/SpellingDictionary/FlagWordsDictionary.test.ts

@@ -8,13 +8,20 @@ import { createTyposDictionary } from './TyposDictionary.js';
 // const oc = <T>(obj: T) => expect.objectContaining(obj);
 
 describe('ForbiddenWordsDictionary', () => {
-    const dictWords = ['  english', '!English', 'grumpy', 'Avocado', 'avocadoS', '!avocado'];
+    const dictWords = ['  english', '!English', 'grumpy', 'Avocado', 'avocadoS', '!avocado', 'Apple', 'orange'];
     const dict = createFlagWordsDictionary(dictWords, 'flag_words', 'test');
 
     test('flag dictionary entries', () => {
-        expect(dict.isForbidden('english')).toBe(true);
-        expect(dict.isForbidden('English')).toBe(false);
-        expect(dict.isForbidden('grumpy')).toBe(true);
+        expect(dict.isForbidden('english'), 'english should be forbidden').toBe(true);
+        expect(dict.isForbidden('English'), 'English should not be forbidden').toBe(false);
+        expect(dict.isForbidden('grumpy'), 'grumpy should be forbidden').toBe(true);
+        expect(dict.isForbidden('Apple'), 'Apple should be forbidden').toBe(true);
+        expect(dict.isForbidden('APPLE'), 'APPLE should not be forbidden').toBe(false);
+        expect(dict.isForbidden('apple'), 'apple should not be forbidden').toBe(false);
+        expect(dict.isForbidden('orange'), 'orange should be forbidden').toBe(true);
+        expect(dict.isForbidden('Orange'), 'Orange should be forbidden').toBe(true);
+        expect(dict.isForbidden('ORANGE'), 'ORANGE should be forbidden').toBe(true);
+        expect(dict.isForbidden('OraNge'), 'OraNge should be forbidden').toBe(true);
         expect(dict.has('English')).toBe(false);
     });
 

packages/cspell-eslint-plugin/src/generated/schema.cts

@@ -152,11 +152,11 @@ export const optionsSchema: Rule.RuleMetaData['schema'] = {
                     "type": "string"
                   },
                   "flagWords": {
-                    "description": "List of words to always be considered incorrect. Words found in `flagWords` override `words`.\n\nFormat of `flagWords`\n- single word entry - `word`\n- with suggestions - `word:suggestion` or `word->suggestion, suggestions`\n\nExample: ```ts \"flagWords\": [   \"color: colour\",   \"incase: in case, encase\",   \"canot->cannot\",   \"cancelled->canceled\" ] ```",
+                    "description": "List of words to always be considered incorrect. Words found in `flagWords` override `words`.\n\nFormat of `flagWords`\n- single word entry - `word`\n- with suggestions - `word:suggestion` or `word->suggestion, suggestions`\n\nExample: ```ts \"flagWords\": [   \"color: colour\",   \"incase: in case, encase\",   \"canot->cannot\",   \"cancelled->canceled\" ] ```\n\nCase Sensitivity:\n\nA word is flagged if it exactly matches an entry, or if its lowercased form exactly matches an entry. In practice this means:\n- An entry written in **all lowercase** (e.g. `avocado`) flags that word in any casing found in the   document — `avocado`, `Avocado`, and `AVOCADO` are all flagged.\n- An entry containing **any uppercase letter** (e.g. `Avocado`) only flags that exact casing —   `avocado` and `AVOCADO` are not flagged.",
                     "items": {
                       "type": "string"
                     },
-                    "markdownDescription": "List of words to always be considered incorrect. Words found in `flagWords` override `words`.\n\nFormat of `flagWords`\n- single word entry - `word`\n- with suggestions - `word:suggestion` or `word->suggestion, suggestions`\n\nExample:\n```ts\n\"flagWords\": [\n  \"color: colour\",\n  \"incase: in case, encase\",\n  \"canot->cannot\",\n  \"cancelled->canceled\"\n]\n```",
+                    "markdownDescription": "List of words to always be considered incorrect. Words found in `flagWords` override `words`.\n\nFormat of `flagWords`\n- single word entry - `word`\n- with suggestions - `word:suggestion` or `word->suggestion, suggestions`\n\nExample:\n```ts\n\"flagWords\": [\n  \"color: colour\",\n  \"incase: in case, encase\",\n  \"canot->cannot\",\n  \"cancelled->canceled\"\n]\n```\n\nCase Sensitivity:\n\nA word is flagged if it exactly matches an entry, or if its lowercased form exactly matches an entry.\nIn practice this means:\n- An entry written in **all lowercase** (e.g. `avocado`) flags that word in any casing found in the\n  document — `avocado`, `Avocado`, and `AVOCADO` are all flagged.\n- An entry containing **any uppercase letter** (e.g. `Avocado`) only flags that exact casing —\n  `avocado` and `AVOCADO` are not flagged.",
                     "type": "array"
                   },
                   "ignoreWords": {
@@ -210,11 +210,11 @@ export const optionsSchema: Rule.RuleMetaData['schema'] = {
           "type": "boolean"
         },
         "flagWords": {
-          "description": "List of words to always be considered incorrect. Words found in `flagWords` override `words`.\n\nFormat of `flagWords`\n- single word entry - `word`\n- with suggestions - `word:suggestion` or `word->suggestion, suggestions`\n\nExample: ```ts \"flagWords\": [   \"color: colour\",   \"incase: in case, encase\",   \"canot->cannot\",   \"cancelled->canceled\" ] ```",
+          "description": "List of words to always be considered incorrect. Words found in `flagWords` override `words`.\n\nFormat of `flagWords`\n- single word entry - `word`\n- with suggestions - `word:suggestion` or `word->suggestion, suggestions`\n\nExample: ```ts \"flagWords\": [   \"color: colour\",   \"incase: in case, encase\",   \"canot->cannot\",   \"cancelled->canceled\" ] ```\n\nCase Sensitivity:\n\nA word is flagged if it exactly matches an entry, or if its lowercased form exactly matches an entry. In practice this means:\n- An entry written in **all lowercase** (e.g. `avocado`) flags that word in any casing found in the   document — `avocado`, `Avocado`, and `AVOCADO` are all flagged.\n- An entry containing **any uppercase letter** (e.g. `Avocado`) only flags that exact casing —   `avocado` and `AVOCADO` are not flagged.",
           "items": {
             "type": "string"
           },
-          "markdownDescription": "List of words to always be considered incorrect. Words found in `flagWords` override `words`.\n\nFormat of `flagWords`\n- single word entry - `word`\n- with suggestions - `word:suggestion` or `word->suggestion, suggestions`\n\nExample:\n```ts\n\"flagWords\": [\n  \"color: colour\",\n  \"incase: in case, encase\",\n  \"canot->cannot\",\n  \"cancelled->canceled\"\n]\n```",
+          "markdownDescription": "List of words to always be considered incorrect. Words found in `flagWords` override `words`.\n\nFormat of `flagWords`\n- single word entry - `word`\n- with suggestions - `word:suggestion` or `word->suggestion, suggestions`\n\nExample:\n```ts\n\"flagWords\": [\n  \"color: colour\",\n  \"incase: in case, encase\",\n  \"canot->cannot\",\n  \"cancelled->canceled\"\n]\n```\n\nCase Sensitivity:\n\nA word is flagged if it exactly matches an entry, or if its lowercased form exactly matches an entry.\nIn practice this means:\n- An entry written in **all lowercase** (e.g. `avocado`) flags that word in any casing found in the\n  document — `avocado`, `Avocado`, and `AVOCADO` are all flagged.\n- An entry containing **any uppercase letter** (e.g. `Avocado`) only flags that exact casing —\n  `avocado` and `AVOCADO` are not flagged.",
           "type": "array"
         },
         "ignoreRegExpList": {

packages/cspell-types/api/index.d.mts

@@ -718,6 +718,15 @@ interface InlineDictionary {
    *   "cancelled->canceled"
    * ]
    * ```
+   *
+   * Case Sensitivity:
+   *
+   * A word is flagged if it exactly matches an entry, or if its lowercased form exactly matches an entry.
+   * In practice this means:
+   * - An entry written in **all lowercase** (e.g. `avocado`) flags that word in any casing found in the
+   *   document — `avocado`, `Avocado`, and `AVOCADO` are all flagged.
+   * - An entry containing **any uppercase letter** (e.g. `Avocado`) only flags that exact casing —
+   *   `avocado` and `AVOCADO` are not flagged.
    */
   flagWords?: string[];
   /**