Implement persistent disk cache with EhCache for TypoDiagnostic with WordStatus enum, separated cache managers, and tested EhCacheAdapter component (#3550)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Nikita Fedkin <[email protected]>

Author: Copilot

.gitignore

@@ -83,4 +83,5 @@ bsl-language-server_*.zip
 *.log
 *.hprof
 /.idea/material_theme_project_new.xml
-__pycache__/
+.bsl-ls-cache/
+__pycache__/

build.gradle.kts

@@ -75,6 +75,7 @@ dependencies {
 
     // кэширование
     api("com.github.ben-manes.caffeine", "caffeine", "3.2.0")
+    api("org.ehcache:ehcache:3.10.8")
 
     // lsp4j core
     api("org.eclipse.lsp4j", "org.eclipse.lsp4j", "0.24.0")
@@ -208,6 +209,14 @@ tasks.test {
 
     val jmockitPath = classpath.find { it.name.contains("jmockit") }!!.absolutePath
     jvmArgs("-javaagent:${jmockitPath}")
+
+    // Cleanup test cache directories after tests complete
+    doLast {
+        val tmpDir = File(System.getProperty("java.io.tmpdir"))
+        tmpDir.listFiles()?.filter { it.name.startsWith("bsl-ls-cache-") }?.forEach { cacheDir ->
+            cacheDir.deleteRecursively()
+        }
+    }
 }
 
 tasks.check {

docs/diagnostics/Typo.md

@@ -6,6 +6,44 @@
 Проверка орфографических ошибок осуществляется с помощью [LanguageTool](https://languagetool.org/ru/). Проверяемые строки разбиваются по camelCase 
 и проверяются на соответствие во встроенном словаре.
 
+## Кэш
+Диагностика использует персистентный кэш на диске (EhCache) для хранения информации об уже проверенных словах. Путь к каталогу кэша задаётся свойством `app.cache.path` в конфигурации приложения.
+
+По умолчанию в приложении установлено:
+
+```properties
+app.cache.path=.bsl-ls-cache
+```
+
+Это означает, что кэш будет создаваться в каталоге `.bsl-ls-cache` относительно рабочей директории приложения (можно переопределить через переменные окружения или аргументы командной строки).
+
+Рекомендации для CI: кэшируйте или переносите этот каталог между сборками, чтобы избежать повторной персистентной инвалидации и ускорить проверки. Ниже — примеры подходов для популярных CI-платформ.
+
+- GitHub Actions
+  - Используйте `actions/cache` для сохранения каталога (`.bsl-ls-cache` или путь, заданный в `app.cache.path`) между прогоном сборок и тестов.
+
+- GitLab CI
+  - В `.gitlab-ci.yml` используйте секцию `cache`:
+
+    ```yaml
+    cache:
+      key: "bsl-ls-typo-cache"
+      paths:
+        - .bsl-ls-cache/
+      policy: pull-push
+    ```
+
+  - При необходимости задайте уникальный `key` для разных веток/раннеров.
+
+- Jenkins
+  - В pipeline можно сохранить каталог кэша между сборками несколькими способами:
+    - Использовать `stash`/`unstash` для передачи данных между этапами в одной сборке.
+    - Использовать плагин `Workspace Cleanup` и настроить сохранение workspace на агенте (если агенты постоянные) или архивировать артефакт с помощью `archiveArtifacts` и скачивать при следующих сборках.
+    - Для Jenkins при использовании динамических агентов (например, Kubernetes) рекомендуется сохранять кэш в сетевом хранилище или в объектном хранилище (S3) и восстанавливать его в начале job.
+
+Общие рекомендации:
+- Убедитесь, что путь, указанный в `app.cache.path`, доступен процессу сборки и имеет достаточные права.
+
 ## Источники
 <!-- Необходимо указывать ссылки на все источники, из которых почерпнута информация для создания диагностики -->
 

src/main/java/com/github/_1c_syntax/bsl/languageserver/diagnostics/TypoDiagnostic.java

@@ -27,13 +27,16 @@
 import com.github._1c_syntax.bsl.languageserver.diagnostics.metadata.DiagnosticSeverity;
 import com.github._1c_syntax.bsl.languageserver.diagnostics.metadata.DiagnosticTag;
 import com.github._1c_syntax.bsl.languageserver.diagnostics.metadata.DiagnosticType;
+import com.github._1c_syntax.bsl.languageserver.diagnostics.typo.CheckedWordsHolder;
 import com.github._1c_syntax.bsl.languageserver.diagnostics.typo.JLanguageToolPool;
+import com.github._1c_syntax.bsl.languageserver.diagnostics.typo.WordStatus;
 import com.github._1c_syntax.bsl.languageserver.utils.Trees;
 import com.github._1c_syntax.bsl.parser.BSLParser;
 import com.github._1c_syntax.bsl.parser.BSLParserRuleContext;
 import com.github._1c_syntax.utils.CaseInsensitivePattern;
 import lombok.AccessLevel;
 import lombok.Getter;
+import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.antlr.v4.runtime.Token;
 import org.apache.commons.lang3.StringUtils;
@@ -49,7 +52,6 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
-import java.util.concurrent.ConcurrentHashMap;
 import java.util.function.Predicate;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
@@ -63,6 +65,7 @@
   }
 )
 @Slf4j
+@RequiredArgsConstructor
 public class TypoDiagnostic extends AbstractDiagnostic {
 
   @Getter(lazy = true, value = AccessLevel.PRIVATE)
@@ -71,14 +74,6 @@ public class TypoDiagnostic extends AbstractDiagnostic {
     "ru", new JLanguageToolPool(Languages.getLanguageForShortCode("ru"))
   );
 
-  /**
-   * Карта, хранящая результат проверки слова (ошибка/нет ошибки) в разрезе языков.
-   */
-  private static final Map<String, Map<String, Boolean>> checkedWords = Map.of(
-    "en", new ConcurrentHashMap<>(),
-    "ru", new ConcurrentHashMap<>()
-  );
-
   private static final Pattern SPACES_PATTERN = Pattern.compile("\\s+");
   private static final Pattern QUOTE_PATTERN = Pattern.compile("\"");
   private static final String FORMAT_STRING_RU = "Л=|ЧЦ=|ЧДЦ=|ЧС=|ЧРД=|ЧРГ=|ЧН=|ЧВН=|ЧГ=|ЧО=|ДФ=|ДЛФ=|ДП=|БЛ=|БИ=";
@@ -100,6 +95,8 @@ public class TypoDiagnostic extends AbstractDiagnostic {
   private static final int DEFAULT_MIN_WORD_LENGTH = 3;
   private static final String DEFAULT_USER_WORDS_TO_IGNORE = "";
 
+  private final CheckedWordsHolder checkedWordsHolder;
+
   @DiagnosticParameter(
     type = Integer.class,
     defaultValue = "" + DEFAULT_MIN_WORD_LENGTH
@@ -166,12 +163,11 @@ private Map<String, List<Token>> getTokensMap(
   protected void check() {
 
     String lang = info.getResourceString("diagnosticLanguage");
-    Map<String, Boolean> checkedWordsForLang = checkedWords.get(lang);
     Map<String, List<Token>> tokensMap = getTokensMap(documentContext);
 
     // build string of unchecked words
     Set<String> uncheckedWords = tokensMap.keySet().stream()
-      .filter(word -> !checkedWordsForLang.containsKey(word))
+      .filter(word -> checkedWordsHolder.getWordStatus(lang, word) == WordStatus.MISSING)
       .collect(Collectors.toSet());
 
     if (uncheckedWords.isEmpty()) {
@@ -201,10 +197,12 @@ protected void check() {
     // check words and mark matched as checked
     matches.stream()
       .map(ruleMatch -> ruleMatch.getSentence().getTokens()[1].getToken())
-      .forEach(word -> checkedWordsForLang.put(word, true));
+      .forEach(word -> checkedWordsHolder.markWordAsError(lang, word));
 
     // mark unmatched words without errors as checked
-    uncheckedWords.forEach(word -> checkedWordsForLang.putIfAbsent(word, false));
+    uncheckedWords.stream()
+      .filter(word -> checkedWordsHolder.getWordStatus(lang, word) == WordStatus.MISSING)
+      .forEach(word -> checkedWordsHolder.markWordAsNoError(lang, word));
 
     fireDiagnosticOnCheckedWordsWithErrors(tokensMap);
   }
@@ -213,10 +211,9 @@ private void fireDiagnosticOnCheckedWordsWithErrors(
     Map<String, List<Token>> tokensMap
   ) {
     String lang = info.getResourceString("diagnosticLanguage");
-    Map<String, Boolean> checkedWordsForLang = checkedWords.get(lang);
 
     tokensMap.entrySet().stream()
-      .filter(entry -> checkedWordsForLang.getOrDefault(entry.getKey(), false))
+      .filter(entry -> checkedWordsHolder.getWordStatus(lang, entry.getKey()) == WordStatus.HAS_ERROR)
       .forEach((Map.Entry<String, List<Token>> entry) -> {
         String word = entry.getKey();
         List<Token> tokens = entry.getValue();

src/main/java/com/github/_1c_syntax/bsl/languageserver/diagnostics/typo/CheckedWordsHolder.java

@@ -0,0 +1,70 @@
+/*
+ * This file is a part of BSL Language Server.
+ *
+ * Copyright (c) 2018-2025
+ * Alexey Sosnoviy <[email protected]>, Nikita Fedkin <[email protected]> and contributors
+ *
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ *
+ * BSL Language Server is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3.0 of the License, or (at your option) any later version.
+ *
+ * BSL Language Server is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with BSL Language Server.
+ */
+package com.github._1c_syntax.bsl.languageserver.diagnostics.typo;
+
+import org.springframework.cache.annotation.CachePut;
+import org.springframework.cache.annotation.Cacheable;
+import org.springframework.stereotype.Component;
+
+/**
+ * Компонент для управления постоянным кэшем проверенных слов для диагностики опечаток.
+ * Использует Spring Cache с EhCache для хранения кэша на диске.
+ */
+@Component
+public class CheckedWordsHolder {
+
+  /**
+   * Получает статус слова из кэша.
+   *
+   * @param lang код языка ("en" или "ru")
+   * @param word слово, статус которого запрашивается
+   * @return WordStatus, указывающий, есть ли у слова ошибка, отсутствует ли ошибка, или слово отсутствует в кэше
+   */
+  @Cacheable(value = "typoCache", key = "#lang + ':' + #word", cacheManager = "typoCacheManager")
+  public WordStatus getWordStatus(String lang, String word) {
+    return WordStatus.MISSING;
+  }
+
+  /**
+   * Помечает слово как содержащее ошибку в кэше.
+   *
+   * @param lang код языка ("en" или "ru")
+   * @param word слово, которое помечается как содержащее ошибку
+   * @return сохранённый WordStatus, указывающий на наличие ошибки
+   */
+  @CachePut(value = "typoCache", key = "#lang + ':' + #word", cacheManager = "typoCacheManager")
+  public WordStatus markWordAsError(String lang, String word) {
+    return WordStatus.HAS_ERROR;
+  }
+
+  /**
+   * Помечает слово как не содержащее ошибку в кэше.
+   *
+   * @param lang код языка ("en" или "ru")
+   * @param word слово, которое помечается как не содержащее ошибку
+   * @return сохранённый WordStatus, указывающий на отсутствие ошибки
+   */
+  @CachePut(value = "typoCache", key = "#lang + ':' + #word", cacheManager = "typoCacheManager")
+  public WordStatus markWordAsNoError(String lang, String word) {
+    return WordStatus.NO_ERROR;
+  }
+}

src/main/java/com/github/_1c_syntax/bsl/languageserver/diagnostics/typo/WordStatus.java

@@ -0,0 +1,42 @@
+/*
+ * This file is a part of BSL Language Server.
+ *
+ * Copyright (c) 2018-2025
+ * Alexey Sosnoviy <[email protected]>, Nikita Fedkin <[email protected]> and contributors
+ *
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ *
+ * BSL Language Server is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3.0 of the License, or (at your option) any later version.
+ *
+ * BSL Language Server is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with BSL Language Server.
+ */
+package com.github._1c_syntax.bsl.languageserver.diagnostics.typo;
+
+/**
+ * Статус результата проверки орфографии слова.
+ */
+public enum WordStatus {
+  /**
+   * Слово содержит орфографическую ошибку.
+   */
+  HAS_ERROR,
+  
+  /**
+   * Слово написано правильно.
+   */
+  NO_ERROR,
+  
+  /**
+   * Слово ещё не проверено.
+   */
+  MISSING
+}

src/main/java/com/github/_1c_syntax/bsl/languageserver/infrastructure/CacheConfiguration.java

@@ -22,19 +22,44 @@
 package com.github._1c_syntax.bsl.languageserver.infrastructure;
 
 import com.github.benmanes.caffeine.cache.Caffeine;
+import com.github._1c_syntax.bsl.languageserver.diagnostics.typo.WordStatus;
+import org.ehcache.config.builders.CacheConfigurationBuilder;
+import org.ehcache.config.builders.CacheManagerBuilder;
+import org.ehcache.config.builders.ResourcePoolsBuilder;
+import org.ehcache.config.units.EntryUnit;
+import org.ehcache.config.units.MemoryUnit;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.cache.CacheManager;
 import org.springframework.cache.annotation.EnableCaching;
 import org.springframework.cache.caffeine.CaffeineCacheManager;
+import org.springframework.cache.support.SimpleCacheManager;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+
+import java.nio.file.Path;
+import java.util.List;
 
 /**
  * Spring-конфигурация кэширования.
+ * <p>
+ * Для typoCache используется EhCache с персистентным хранилищем на диске.
+ * Для остальных кэшей (например, code lens) используется Caffeine с хранением в памяти.
  */
 @Configuration
 @EnableCaching
 public class CacheConfiguration {
+
+  private static final String TYPO_CACHE_NAME = "typoCache";
+
+  /**
+   * Основной менеджер кэша, использующий Caffeine для кэширования в памяти.
+   * <p>
+   * Помечен как {@code @Primary}, поэтому используется для всех кэшей по умолчанию,
+   * если не указан явно другой менеджер кэша (например, {@code typoCacheManager} для typoCache).
+   */
   @Bean
+  @Primary
   public CacheManager cacheManager(Caffeine<Object, Object> caffeine) {
     var caffeineCacheManager = new CaffeineCacheManager();
     caffeineCacheManager.setCaffeine(caffeine);
@@ -45,4 +70,48 @@ public CacheManager cacheManager(Caffeine<Object, Object> caffeine) {
   public Caffeine<Object, Object> caffeineConfig() {
     return Caffeine.newBuilder();
   }
+
+  /**
+   * Выделенный менеджер EhCache для typoCache с персистентным хранением на диске.
+   * <p>
+   * Настроен программно, без использования XML-конфигурации.
+   * При закрытии Spring-контекста вызывается метод {@code close()} для корректного завершения работы кэша.
+   */
+  @Bean(destroyMethod = "close")
+  public org.ehcache.CacheManager ehcacheManager(
+    @Value("${app.cache.path}") String cacheDirPath
+  ) {
+    var cacheDir = Path.of(cacheDirPath);
+    
+    // Configure EhCache cache with disk persistence
+    var cacheConfig = CacheConfigurationBuilder
+      .newCacheConfigurationBuilder(
+        String.class,
+        WordStatus.class,
+        ResourcePoolsBuilder.newResourcePoolsBuilder()
+          .heap(125_000, EntryUnit.ENTRIES)
+          .disk(50, MemoryUnit.MB, true)
+      )
+      .build();
+
+    // Build native EhCache manager with persistence
+    return CacheManagerBuilder.newCacheManagerBuilder()
+      .with(CacheManagerBuilder.persistence(cacheDir.toFile()))
+      .withCache(TYPO_CACHE_NAME, cacheConfig)
+      .build(true);
+  }
+
+  @Bean
+  public CacheManager typoCacheManager(org.ehcache.CacheManager ehcacheManager) {
+    var nativeCache = ehcacheManager.getCache(TYPO_CACHE_NAME, String.class, WordStatus.class);
+    
+    // Wrap the native cache with EhCacheAdapter
+    var simpleCacheManager = new SimpleCacheManager();
+    simpleCacheManager.setCaches(List.of(
+      new EhCacheAdapter<>(nativeCache, TYPO_CACHE_NAME)
+    ));
+    simpleCacheManager.afterPropertiesSet();
+    
+    return simpleCacheManager;
+  }
 }