* feat(scala): Add stale lock detection for Metals H2 database
Add detection and automatic cleanup of stale Metals H2 database locks
to improve multi-instance support. When a Metals process crashes without
proper cleanup, it can leave a lock file that prevents proper AUTO_SERVER
coordination with new instances.
Changes:
- Add metals_db_utils.py with detection logic for stale locks
- Add StaleLockMode enum (auto-clean/warn/fail) for configurable behavior
- Add MetalsStaleLockError exception for fail mode
- Integrate stale lock checking into ScalaLanguageServer init
- Add configuration options: on_stale_lock, log_multi_instance_notice
- Add comprehensive unit tests for detection logic
This enhancement allows Serena's Metals to coexist with VS Code or other
editors running Metals on the same project, with proper handling of edge
cases like crashed processes.
* test(scala): Add integration tests for stale lock handling modes
Add 7 integration tests for ScalaLanguageServer stale lock detection:
- AUTO_CLEAN mode cleans stale locks and proceeds
- WARN mode logs warning without cleanup
- FAIL mode raises MetalsStaleLockError
- ACTIVE_INSTANCE logs info when notice enabled
- ACTIVE_INSTANCE silent when notice disabled
- NO_DATABASE proceeds silently
- NO_LOCK proceeds silently
Tests use mocking to avoid requiring Java/Coursier/Metals.
* docs(scala): Add multi-instance and stale lock documentation
Document Metals multi-instance support via H2 AUTO_SERVER:
- Explain how multiple Metals instances share database and Bloop
- Document memory considerations (~500MB per JVM)
- Add stale lock detection configuration options
- Document on_stale_lock modes (auto-clean, warn, fail)
- Add YAML configuration examples
* docs: Clean up docs
Removed memory considerations and additional configuration sections from the Scala setup guide.
* refactor(scala): Extract settings helper and add module-level constants
- Add DEFAULT_METALS_VERSION, DEFAULT_CLIENT_NAME, DEFAULT_ON_STALE_LOCK,
DEFAULT_LOG_MULTI_INSTANCE_NOTICE constants to eliminate duplication
- Extract _get_scala_settings() pure function for centralized settings parsing
- Remove redundant cleanup_stale_lock import
- Add warning log when AUTO_CLEAN mode fails to remove stale lock
- Simplify lock path handling with ternary expression
This refactoring improves code maintainability by centralizing Scala
settings extraction and applying functional programming principles.
* chore(scala): fix typo in docstring and comments
- Add check in conftest.py to disable PHP_PHPACTOR tests when php binary
is not found
- Refactor test_php_basic.py to use dynamic PHP server list based on
availability
- Ensure tests for PHP_PHPACTOR are only parametrized if PHP is present
This fixes a bug: _sanitize_symbol_dict was not recursively applied
to children, causing children to contain superfluous entries
(full location, etc.)
Additional change: Improve factorisation of symbol overview computation
It represents a reasonable compromise between pragmatism and type-safety.
Soundness is checked at runtime, but if the grouper is instantiated statically,
then we immediately detect misspecification.
One example application is implemented in GetSymbolsOverviewTool
Provides basis for #1021
Remove serena_config storage from RegisteredProject; instead accept it
as an explicit parameter in get_project_instance() for cleaner separation
of concerns.
Replace `global_ignored_paths: Sequence[str]` with `serena_config: SerenaConfig | None`
in Project.__init__ and propagate through RegisteredProject for more general and
future-proof interfaces.
TJ Kolleh