docs: update release notes for v2.5.0 with

Author: d-biehl

docs/news/2026-03-31-whats-new-v2.5.0.md

@@ -5,98 +5,117 @@ date: 2026-03-31
 
 # What's New in RobotCode v2.5.0
 
-This release brings **major performance improvements**, a powerful new **SQLite-based cache system**, and smarter **code completion** — making RobotCode faster and more productive than ever, especially for large projects.
+If you've ever opened a large Robot Framework project and gone for coffee while RobotCode was still thinking — this release is for you. Version 2.5.0 is all about **speed**: faster startup, faster analysis, faster code completion. And a few new tricks on top.
 
-## Highlights
+## Instant Startup with Analysis Caching
 
-### Blazing-Fast Startup with Namespace Caching
+The biggest change you'll notice: **RobotCode remembers**. When you open a project for the second time, all the analysis work from your last session is still there — diagnostics, code completion, navigation, everything loads almost instantly.
 
-The biggest highlight of this release is the new **namespace disk cache**. RobotCode now caches fully resolved namespace data to a SQLite database, so on subsequent IDE starts cached namespaces are reused instead of re-analyzing every file from scratch. This dramatically reduces the time until diagnostics, code completion, and navigation become available — especially in large workspaces with hundreds of Robot files.
+Behind the scenes, RobotCode now stores fully resolved analysis data in a local SQLite database. Instead of re-analyzing every file on every IDE start, it loads cached results and only re-processes files that actually changed. For projects with hundreds of Robot files, this can cut startup from minutes down to seconds.
 
-- **Enabled by default** — no configuration needed; just enjoy faster startups.
-- **Automatic invalidation** — the cache is rebuilt when source files, library dependencies, environment variables, command-line variables, language settings, or the RobotCode version change.
-- **SQLite backend** — all cache entries are consolidated into a single SQLite database per workspace, replacing the old scattered `.pkl` files.
-- **Advisory file locking** — concurrent access from multiple processes (language server, CLI, analyze) is safe thanks to `fcntl.flock`-based locking.
+This is **enabled by default** — there's nothing to configure. The cache is automatically invalidated when your source files change, when library dependencies are updated, when environment variables or command-line variables differ, or when you update RobotCode itself. If something changes, the affected parts are re-analyzed — everything else comes straight from cache.
 
-### Cache Management CLI
+Since this is a new feature, you can disable it if you run into any issues:
 
-A new `robotcode analyze cache` command group gives you full control over the cache:
+```toml
+# robot.toml
+[tool.robotcode-analyze.cache]
+cache-namespaces = false
+```
+
+or via the CLI:
+
+```bash
+robotcode analyze --no-cache-namespaces
+```
+
+Multiple processes (the language server, CLI commands, parallel analyze runs) can safely access the cache at the same time thanks to file-level locking. No corruption, no conflicts.
+
+## Performance: The Numbers
+
+Even without the cache, this release is noticeably faster. Here's what changed:
+
+- **No more 30-minute hangs on large projects.** Robot Framework's `variable_not_found` runs a fuzzy "Did you mean…?" search on every unresolved variable — a nice idea, but O(n×m) over all variable candidates. For big projects (375+ files), this could freeze the analysis for over 30 minutes. RobotCode now skips that search entirely since it never uses the suggestion text. Problem solved. ([#587](https://github.com/robotcodedev/robotcode/issues/587))
+
+- **Keyword matching is 94% faster.** The `KeywordMatcher` used to be instantiated from scratch on every lookup — about 7.5 million times per analysis run. It's now cached on the `KeywordDoc` itself. Combined with a new dict-based index in `KeywordStore`, keyword lookups went from linear scan to O(1) for non-embedded keywords. Overall analysis time dropped by **22%** with **31% fewer function calls**.
+
+- **File resolution is 28% faster.** Swapping `pathlib.Path` for `os.path` string operations in the hot path of file resolution plus lazy-caching of valid `sys.path` entries cut warm-start wall time by nearly a third.
+
+- **Less memory per document.** Each document used to keep two cached AST models. Now there's just one, saving around 200–500 KB per file. That adds up quickly in a big workspace.
 
-| Command | Description |
-|---------|-------------|
-| `path`  | Print the resolved cache directory |
-| `info`  | Show cache statistics with per-section breakdown |
-| `list`  | List cached entries with glob pattern filtering (`-p`) |
-| `clear` | Remove cached entries by section |
-| `prune` | Delete the entire cache database |
+- **Faster cache loading.** Cached namespace data now includes source hints that let RobotCode skip expensive filesystem lookups (`find_resource`) when the cached paths still exist on disk. Cache entries use lazy deserialization — data blobs are only unpickled on actual cache hits, not on every lookup.
 
-You can also override the cache location via the `ROBOTCODE_CACHE_DIR` environment variable — the VS Code extension sets this automatically in the integrated terminal.
+- **`ArgumentSpec.resolve()` actually caches now.** A subtle bug caused `RobotArgumentSpec` to be recreated on every call (100K times per run) instead of being cached. Fixed — instantiation calls dropped by **98.7%**.
 
-### Code Completion for `Literal` Type Hints
+## Smarter Code Completion for Type Hints
 
-Keywords with `Literal["fast", "slow", "auto"]` type hints now show their allowed values directly in the completion list. No more switching to documentation just to find valid argument values. Supports `Union` types containing `Literal` as well.
+If you write Python libraries with type hints like `Literal["fast", "slow", "auto"]`, RobotCode now picks up on those and shows the allowed values directly in the completion list. This works for `Union` types containing `Literal` too, so `Literal["x", "y"] | int` will offer `x` and `y` as suggestions.
 
-### Unused Keywords & Variables Detection on CLI
+No more switching to the library docs just to look up which string values a keyword accepts — the editor tells you right there.
 
-The `robotcode analyze code` command now supports collecting unused keyword and variable diagnostics. Enable it in `robot.toml`:
+## Find Unused Keywords & Variables from the CLI
+
+Unused keywords and variables are the kind of thing that quietly accumulates in any project. RobotCode can now detect them when running `robotcode analyze code` from the command line — great for CI pipelines or periodic cleanup sessions.
+
+Enable it in your `robot.toml`:
 
 ```toml
 [tool.robotcode-analyze.code]
 collect-unused = true
 ```
 
-Or use the CLI flags directly:
+Or toggle it per invocation:
 
 ```bash
 robotcode analyze code --collect-unused
 robotcode analyze code --no-collect-unused
 ```
 
----
+## Full Control over the Analysis Cache
 
-## Performance
+A new `robotcode analyze cache` command group gives you visibility into what's cached and lets you manage it when needed:
 
-This release includes a wave of performance optimizations that significantly reduce analysis time and memory usage:
+```bash
+robotcode analyze cache path     # where is the cache stored?
+robotcode analyze cache info     # cache statistics, per-section breakdown
+robotcode analyze cache list     # list cached entries (supports glob filtering with -p)
+robotcode analyze cache clear    # remove cached entries by section
+robotcode analyze cache prune    # wipe the entire cache
+```
 
-| Optimization | Impact |
-|---|---|
-| **Patch RF's `variable_not_found`** | Skips slow `RecommendationFinder` — fixes 30+ min hangs on large projects ([#587](https://github.com/robotcodedev/robotcode/issues/587)) |
-| **Replace pathlib with `os.path`** | Warm namespace-cache scenario: **-28.3%** wall time |
-| **Cache `KeywordMatcher` + dict-index** | Keyword matching: **-94%**, overall analysis: **-22%**, function calls: 118M → 81M |
-| **Fix `ArgumentSpec.resolve()` caching** | `RobotArgumentSpec.__init__` calls: 100K → 1.3K (**-98.7%**) |
-| **Single AST model per document** | Saves ~500 KB/doc (CLI) and ~200 KB/doc (Language Server) |
-| **Namespace cache source hints** | Skips expensive `find_resource()` filesystem searches on warm start |
-| **Lazy `CacheEntry` deserialization** | Data blobs are only unpickled on cache hit |
-| **Cache `get_module_spec` results** | Avoids repeated importlib lookups |
+All output respects `--format` (text/json/toml) and `--no-color`, so it plays nicely with scripts and CI.
 
----
+You can also point the cache to a custom directory via the `ROBOTCODE_CACHE_DIR` environment variable. The VS Code extension automatically sets this in the integrated terminal, so your CLI commands and the language server always share the same cache without any manual setup.
 
 ## Bug Fixes
 
-- **Relative library path resolution** — Namespace cache validation no longer fails for relative imports like `../../resources/libraries/common.py`, preventing unnecessary full rebuilds on every warm start.
-- **Variable name trailing `=`** — Variable names in resource builder now correctly strip trailing `=` ([#546](https://github.com/robotcodedev/robotcode/issues/546)).
-- **Model source field** — RobotCode no longer overrides the `source` field on AST blocks when newer Robot Framework versions already set it ([#588](https://github.com/robotcodedev/robotcode/issues/588)).
-- **`__init__.py` file check** — Corrected file type check in `_is_valid_file` function.
-- **Thread safety** — Added lock for `_workspace_languages` to prevent race conditions on concurrent access.
+- Fixed cache validation for libraries imported via relative paths — no longer triggers unnecessary full rebuilds on warm start.
+- Variable names with trailing `=` are now stripped correctly by the resource builder ([#546](https://github.com/robotcodedev/robotcode/issues/546)).
+- RobotCode no longer overrides the `source` field on AST blocks when Robot Framework itself already sets it ([#588](https://github.com/robotcodedev/robotcode/issues/588)).
+- Fixed a race condition when accessing workspace language settings in multi-workspace setups.
 
----
+## Under the Hood
+
+A lot of internal work went into this release to prepare for future features:
+
+- **Workspace-wide reference index (ProjectIndex)** — RobotCode now maintains an incrementally updated inverse index across your entire workspace. When a file changes, only its references are updated instead of scanning everything. This covers keywords, variables, namespace entries, keyword tags, testcase tags, and metadata. This is the foundation for upcoming features like unused import detection, import dependency visualization, and call hierarchy — stay tuned.
 
-## Internal Improvements
+- **Namespace refactoring** — The old monolithic `Namespace` class has been split into a clean data container (`Namespace` DTO) built by a dedicated `NamespaceBuilder`, with separate modules for import resolution, AST analysis, variable scoping, and scope trees. This makes the codebase more maintainable and easier to extend.
 
-- **ProjectIndex** — New incrementally maintained inverse reference index for O(1) workspace-wide lookups of keywords, variables, namespace entries, tags, and metadata.
-- **Tag & metadata reference tracking** — Structured reference tracking for keyword tags, testcase tags, and metadata during analysis, enabling future features like tag-based navigation.
-- **`RF_VERSION` constant** — Replaced ~134 `get_robot_version()` call sites with a single module-level constant. Removed all dead code for Robot Framework < 5.0.
-- **Namespace refactoring** — Split the monolithic `Namespace` class into a pure DTO with event-driven invalidation, separate builder, and focused modules for import resolution, AST analysis, and variable scoping.
-- **JSON file watching** — `.json` files are now included in the watched file extensions for automatic workspace updates.
-- **Deprecated robocop options removed** — Legacy robocop configuration options have been removed.
-- **Resource lifecycle hardening** — Replaced fragile `__del__`-based cleanup in JSON-RPC layer with explicit `close`/`close_async` paths and best-effort weakref finalizers.
+- **`RF_VERSION` constant** — All ~134 scattered `get_robot_version()` call sites have been replaced with a single module-level constant. All dead code for Robot Framework < 5.0 (which is no longer supported) has been removed.
+
+- **JSON file watching** — `.json` files are now included in the watched file extensions, so changes to JSON-based configuration are picked up automatically.
+
+- **Deprecated Robocop options removed** — Legacy robocop configuration options that were deprecated in earlier releases have been cleaned up.
 
 ---
 
 ## Thank You
 
 Thanks to everyone who reported issues, contributed ideas, and tested pre-release builds. Your feedback drives every release.
 
+For the full list of changes, see the [Changelog](https://github.com/robotcodedev/robotcode/blob/main/CHANGELOG.md).
+
 - [Report issues](https://github.com/robotcodedev/robotcode/issues)
 - [Discussions & Q&A](https://github.com/robotcodedev/robotcode/discussions)
 - [Sponsor RobotCode](https://opencollective.com/robotcode)