Provide warning on config files that are not currently configured for the project

[evie-lau]

Following up on discussion in #213 (comment), with the change to allow LCLS support for all bootstrap.properties and server.env files, it is possible to start editing files that have not yet been configured for the Liberty project to use.

Suggestion for enhancement to provide a warning if the currently edited file is not configured for Liberty to use.

Needs design discussion

• Diagnostic probably won't work because there is no particular text to highlight.
• Could possibly provide a toast/popup notification.

This would also be affected by the fact that liberty-plugin-config.xml may not have been generated yet in a new or cleaned project, which may raise the warning until the project is built (liberty:create). An idea has been raised to possibly automatically run a lightweight mvn/gradle goal to generate the liberty-plugin-config.xml

[venmanyarun]

After design discussion, below is the design approved, which would include support for variable processing using the mocked directory structure as well

Liberty Config Language Server (LCLS) Flow

A. Extension Startup

Step 1: Initialize Extension

LemMinX (XML Language Server) starts and loads Liberty extension. Registers completion, hover, diagnostics, code actions, and document link participants.

Step 2: Discover Workspaces

LibertyProjectsManager receives workspace folders from IDE, recursively searches for XML files with <server> root element, detects multi-module Maven and Gradle projects, and creates LibertyWorkspace instances.

Step 3: Initialize Variables Map

Calls SettingsService to initialize empty variables map. Map is created but not populated with values yet. Actual variable population happens on-demand when needed. This ensures map is never null when accessed later.

Step 4: Start File Monitoring

FileWatchService monitors workspace directories for changes to server.xml, bootstrap.properties, server.env, jvm.options, and files referenced via <include> elements. When changes detected, triggers variable reload for affected workspace.

B. File Open Detection (Diagnostics Trigger)

Step 1: File Open Event

User opens server.xml or any Liberty config file in IDE. LemMinX triggers LibertyDiagnosticParticipant doDiagnostics() method.

Step 2: Trigger Automatic Config Generation

Gets workspace folder for the opened document. Checks if project has Liberty Maven or Gradle plugin configured in build file. Calls needsConfigGeneration() to determine if regeneration is needed. If needed, executes prepare-config command with 5-second timeout.

Step 3: Check for Configuration File (needsConfigGeneration)

Performs four checks to determine if config generation is needed:

Check 1: Config file doesn't exist

• Maven: Looks for liberty-plugin-config.xml in target directory
• Gradle: Looks for liberty-plugin-config.xml in build directory
• If not found, removes project from processed cache and returns true

Check 2: Config points to mock server but mock directory missing

• Reads config file and verifies mock directory exists
• Maven: Checks for target/tmp/wlp/usr/servers/{serverName} directory
• Gradle: Checks for build/tmp/wlp/usr/servers/{serverName} directory
• If missing (e.g., after clean), returns true

Check 3: Already processed in this session

• Checks if project path exists in processedProjects set
• If found, returns false to skip generation

Check 4: Config is stale (older than build file)

• Compares timestamps of liberty-plugin-config.xml and build file
• Maven: Compares with pom.xml timestamp
• Gradle: Compares with build.gradle or build.gradle.kts timestamp
• If config older, returns true

If all checks pass, returns false indicating no generation needed.

Step 4: Execute Config Generation

Detects build tool and constructs appropriate command:

• Maven: mvn liberty:prepare-config
• Gradle: ./gradlew libertyPrepareConfig or gradlew.bat libertyPrepareConfig (Windows)

Creates ProcessBuilder, executes command, captures output, and checks exit code. Returns ConfigGenerationResult with success status, error message, and duration.

Step 5: Handle Generation Result

If Successful:

• Config file now exists with mock server structure created
• Adds project to processedProjects set
• Immediately calls SettingsService to reload variables for this workspace
• Variables are populated from newly generated config
• Proceeds with full diagnostic features

If Failed:

• Creates .libertyls/prepare-config directory and saves detailed error log to build.log
• Marks project as failed with error message and log file path
• Proceeds to show failure diagnostic to user

If Timeout (>5 seconds):

• Allows generation process to continue in background
• Config will be checked again on next diagnostic trigger or variable access

Step 6: Reload Variables After Successful Generation

After successful config generation, calls SettingsService populateVariablesForWorkspace() method. Reads newly generated liberty-plugin-config.xml, extracts directory paths, creates ServerConfigDocument, loads default Liberty properties and custom properties from bootstrap.properties, and stores variables in map.

Step 7: Show Failure Diagnostic (If Generation Failed)

If project marked as failed, creates warning diagnostic at line 1 of server.xml with error summary, resolution steps specific to Maven or Gradle, and clickable link to detailed error log at .libertyls/prepare-config/build.log.

Diagnostic Message Format:

Liberty configuration generation failed. Language server features may be limited.

Error: [Brief error summary from Maven/Gradle output]

To resolve:
1. Run 'mvn liberty:prepare-config' manually to see full error
2. Ensure liberty-maven-plugin version 3.13+ is configured
3. Check build.log in .libertyls/ directory for details

[View detailed error log](.libertyls/build.log)

Maven Resolution Steps:

1. Ensure liberty-maven-plugin version 3.11 or later
2. Run 'mvn liberty:prepare-config' manually
3. Check pom.xml configuration
4. Verify Maven is installed

Gradle Resolution Steps:

1. Ensure liberty-gradle-plugin version 3.11 or later
2. Run 'gradle libertyPrepareConfig' manually
3. Check build.gradle configuration
4. Verify Gradle is installed

Step 8: Perform Standard Diagnostics

After handling config generation, proceeds with standard Liberty diagnostics: validates XML structure, checks feature names, validates variable references, checks file paths in <include> elements, validates configuration values, and checks for deprecated features. All diagnostics use data from mock server structure.

C. File Change Detection (FileWatchService)

FileWatchService monitors changes to Liberty configuration files in two locations:

1. Source Config Directory (src/main/liberty/config/):

• Monitors for ANY file changes in the source config directory
• When change detected, automatically triggers prepare-config to sync changes to mock server
• After successful regeneration, immediately reloads variables from updated mock server
• Provides seamless developer experience - changes take effect automatically

2. Mock Server Directory (target/tmp/wlp/usr/servers/{serverName}/ or build/tmp/wlp/usr/servers/{serverName}/):

• Monitors for changes to config files in the mock server
• When change detected, reloads variables without regenerating config
• Handles cases where mock server is modified directly

Flow when source config file changes:

1. FileWatchService detects file modification in src/main/liberty/config/ or any of its sub folders
2. Triggers prepare-config goal/task to regenerate mock server
3. Maven/Gradle plugin copies updated files from source to mock server
4. Resolves build properties in updated files
5. Generates new liberty-plugin-config.xml
6. Immediately calls SettingsService populateVariablesForWorkspace() method
7. Re-reads config and configuration files from updated mock server
8. Updates variable values in workspace variable map
9. Next diagnostic run uses updated values - no IDE restart required