feat: ability to auto-update the language definitions on settings change (#53)

* feat: enable the language definitions to be auto-updated on settings change

- Added new `updateLanguageDefinitions` function in Configuration class to update the language definitions.

- Refactored the `onDidChangeConfiguration` event in the `activate` function of the extension to auto-update the language definitions and reconfigure the comment blocks when a user changes the settings. It uses the new `updateLanguageDefinitions` function to update the definitions before reconfiguring the comment blocks.

- Removed the old `reloadRequiredSettings` array and the `showReloadMessage` function.

* perf: cache default configs to reduce redundant repeated disk reads.

- Added new Configuration class properties:
    - `defaultMultiLineConfig` to store the default multi-line configuration object.
    - `languagesToSkip` to store the languages to skip object.

- Refactored `getLanguagesToSkip` method to get the languages from the new `languagesToSkip` class property instead of repeatedly reading the `skip-languages.jsonc` file from disk on every loop iteration of the `findAllLanguageConfigFilePaths` method.

- Refactored `setLanguageConfiguration` method to get the default config from the new `defaultMultiLineConfig` class property instead of repeatedly reading the `default-multi-line-config.json` file from disk on every loop iteration of the `configureCommentBlocks` method.

- Added a once-per-activation disk read of the `default-multi-line-config.json` and `skip-languages.jsonc` files in the Configuration `constructor` method, and add their contents to the respective new properties. This caches the JSON objects in memory ready for later use, enhancing performance by not reading them from disk on every loop iteration.

* perf: only write language definitions to file in development mode.

Writing to the auto generated language definition files is not very useful in production and are only helpful in development. In production, they are only ever read from disk to log their data for debugging.
So for performance, they should only be written when in development/testing mode, and the updated definitions should only be cached in memory in production mode.

- Removed the `writeCommentLanguageDefinitionsToJsonFile` method calls from the `constructor` and `updateLanguageDefinitions` methods.

- Refactored `writeCommentLanguageDefinitionsToJsonFile` method:

    - Changed the visibility of the method from `private` to `public`, so it can be called from outside of the class.

    - Extracted the call to the `convertMapToReversedObject` utils function into a new method: `getSingleLineLanguageDefinitions`. This method returns the formatted and reversed single-line definitions object ready for logging or writing to JSON file.

    - Extracted the `Object.fromEntries` call into a new method: `getMultiLineLanguageDefinitions`. This method returns the formatted multi-line definitions object ready for logging or writing to JSON file.

    - Changed the `writeJsonFile` method calls to get the data from the 2 new methods instead of the old removed variables.

- Changed the logging of the language definitions in `logDebugInfo` method to get the data from the new `getMultiLineLanguageDefinitions` and `getSingleLineLanguageDefinitions` methods, instead of reading directly from disk.

- Added a conditional in the `activate` function to only run the `writeCommentLanguageDefinitionsToJsonFile` Configuration method when the context of the extension is not running in production (ie. it's running in development or testing mode).

The same conditional is added into the configuration change event so when the definitions auto update they are written to the files in development/testing mode.

* chore(tsconfig): enable auto type acquisition

This helps vscode to show intellisense on native JS functions.

* fix: auto-update definitions on change of the multi-line comments override.

While adding a multi-line override in the `overrideDefaultLanguageMultiLineComments` setting auto-updated the language definitions correctly and used the override style, removing the override didn't work and it was still in place internally in vscode, and the extension's auto-complete no-longer worked.

This happened because the override was inadvertently changing the multi-line style in the cached internal language config whilst also changing it on the shallow-copy for the immediate setting into vscode. So without ever changing it back as it was never supposed to be changed, the override was still apart of the extension's cached language configs making it permanent and breaking functionality.

- Fixed by deep-cloning the `internalLangConfig` using JavaScript's `structuredClone` function in `setLanguageConfiguration` method so mutations (like comment overrides) never write back into the cached `languageConfigs` Map, which prevents pollution during definition auto-updates.

- Added deep-cloning of the comments object in the cached `defaultMultiLineConfig` using `structuredClone` to prevent shared references and accidental mutations down the line during the fallback assignment.

- Update comment override assignment to construct a new block comment tuple while preserving the ending, instead of mutating the existing array in place.

Author: yCodeTech

src/configuration.ts

@@ -76,17 +76,32 @@ export class Configuration {
 	 */
 	private readonly multiLineLangDefinitionFilePath: string = `${this.autoGeneratedDir}/multi-line-languages.json`;
 
+	/**
+	 * The default multi-line configuration.
+	 */
+	private readonly defaultMultiLineConfig: vscode.LanguageConfiguration;
+
+	/**
+	 * The languages to skip, like plaintext, that don't have comment syntax.
+	 */
+	private readonly languagesToSkip: JsonObject;
+
 	/***********
 	 * Methods *
 	 ***********/
 
 	public constructor() {
+		const configPath = `${__dirname}/../../config`;
+		// Read the default multi-line config from the JSON file and cache it for later use.
+		this.defaultMultiLineConfig = utils.readJsonFile(`${configPath}/default-multi-line-config.json`) as vscode.LanguageConfiguration;
+		// Read the languages to skip from the JSON file and cache it for later use.
+		this.languagesToSkip = utils.readJsonFile(`${configPath}/skip-languages.jsonc`);
+
 		this.findAllLanguageConfigFilePaths();
 		this.setLanguageConfigDefinitions();
 
 		this.setMultiLineCommentLanguageDefinitions();
 		this.setSingleLineCommentLanguageDefinitions();
-		this.writeCommentLanguageDefinitionsToJsonFile();
 
 		this.logDebugInfo();
 	}
@@ -300,8 +315,7 @@ export class Configuration {
 	 * @returns {JsonArray}
 	 */
 	private getLanguagesToSkip(): JsonArray {
-		const json = utils.readJsonFile(`${__dirname}/../../config/skip-languages.jsonc`);
-		return json.languages as JsonArray;
+		return this.languagesToSkip.languages as JsonArray;
 	}
 
 	/**
@@ -662,24 +676,53 @@ export class Configuration {
 		this.singleLineBlocksMap.set("customSupportedLanguages", new Map([...tempMap].sort()));
 	}
 
+	/**
+	 * Get the single-line language definitions object
+	 * formatted and reversed by comment style for
+	 * logging and development debug file output.
+	 *
+	 * @returns {SingleLineLanguageDefinitions}
+	 */
+	public getSingleLineLanguageDefinitions(): SingleLineLanguageDefinitions {
+		return utils.convertMapToReversedObject<SingleLineLanguageDefinitions>(this.singleLineBlocksMap);
+	}
+
+	/**
+	 * Get the multi-line language definitions object
+	 * formatted for logging and development debug file output.
+	 *
+	 * @returns {MultiLineLanguageDefinitions}
+	 */
+	public getMultiLineLanguageDefinitions(): MultiLineLanguageDefinitions {
+		return Object.fromEntries(this.multiLineBlocksMap) as unknown as MultiLineLanguageDefinitions;
+	}
+
 	/**
 	 * Write Comment Language Definitions to the respective JSON file:
 	 * either multi-line-languages.json, or single-line-languages.json.
 	 */
-	private writeCommentLanguageDefinitionsToJsonFile() {
+	public writeCommentLanguageDefinitionsToJsonFile() {
 		// Ensure the auto-generated directory exists.
 		utils.ensureDirExists(this.autoGeneratedDir);
 
-		// Convert the singleLineBlocksMap to an object.
-		const singleLineData = utils.convertMapToReversedObject<SingleLineLanguageDefinitions>(this.singleLineBlocksMap);
-
-		const multiLineData = Object.fromEntries(this.multiLineBlocksMap) as unknown as MultiLineLanguageDefinitions;
-
 		// Write into the single-line-languages.json file.
-		utils.writeJsonFile(this.singleLineLangDefinitionFilePath, singleLineData);
+		utils.writeJsonFile(this.singleLineLangDefinitionFilePath, this.getSingleLineLanguageDefinitions());
 
 		// Write into the multi-line-languages.json file.
-		utils.writeJsonFile(this.multiLineLangDefinitionFilePath, multiLineData);
+		utils.writeJsonFile(this.multiLineLangDefinitionFilePath, this.getMultiLineLanguageDefinitions());
+	}
+
+	/**
+	 * Update language definitions.
+	 */
+	public updateLanguageDefinitions() {
+		// Remove all elements from the current Map, so we can update
+		// the definitions with an empty Map.
+		this.singleLineBlocksMap.clear();
+		this.multiLineBlocksMap.clear();
+		// Update the definitions.
+		this.setSingleLineCommentLanguageDefinitions();
+		this.setMultiLineCommentLanguageDefinitions();
 	}
 
 	/**
@@ -693,7 +736,7 @@ export class Configuration {
 	 *
 	 * This method performs the following tasks:
 	 * - Retrieves the internal language configuration for the specified language ID.
-	 * - Reads the default multi-line configuration from a JSON file.
+	 * - Uses the cached default multi-line configuration.
 	 * - Merges the default multi-line configuration with the internal language configuration if
 	 *   multiLine is `true`.
 	 * - Sets the appropriate comment styles and onEnter rules.
@@ -705,14 +748,17 @@ export class Configuration {
 	 * with rogue characters being inserted on new lines.
 	 */
 	private setLanguageConfiguration(langId: LanguageId, multiLine?: boolean, singleLineStyle?: SingleLineCommentStyle): vscode.Disposable {
-		const internalLangConfig: vscode.LanguageConfiguration = this.getLanguageConfig(langId);
-		const defaultMultiLineConfig = utils.readJsonFile(`${__dirname}/../../config/default-multi-line-config.json`) as vscode.LanguageConfiguration;
+		const internalLangConfig: vscode.LanguageConfiguration | undefined = this.getLanguageConfig(langId);
 
-		let langConfig = {...internalLangConfig};
+		// Deep-clone the internalLangConfig so modifications never write back
+		// into the cached `languageConfigs` Map by accident.
+		let langConfig: vscode.LanguageConfiguration = internalLangConfig
+			? structuredClone(internalLangConfig)
+			: {};
 
 		if (multiLine) {
 			langConfig.autoClosingPairs = utils.mergeArraysBy<vscode.AutoClosingPair>(
-				defaultMultiLineConfig.autoClosingPairs,
+				this.defaultMultiLineConfig.autoClosingPairs,
 				internalLangConfig?.autoClosingPairs,
 				"open"
 			);
@@ -725,13 +771,17 @@ export class Configuration {
 			);
 
 			// Only assign the default config comments if it doesn't already exist.
-			// (nullish assignment operator ??=)
-			langConfig.comments ??= defaultMultiLineConfig.comments;
+			// Clone the comments to avoid modifying the original object down the line.
+			langConfig.comments ??= structuredClone(this.defaultMultiLineConfig.comments);
 
 			// If the default multi-line comments has been overridden for the langId,
-			// add the overridden multi-line comments to the langConfig.
-			if (this.isLangIdMultiLineCommentOverridden(langId)) {
-				langConfig.comments.blockComment[0] = this.getOverriddenMultiLineComment(langId);
+			// AND the langConfig has a comments key with a blockComment key, then
+			// update the opening comment style while preserving the ending.
+			if (this.isLangIdMultiLineCommentOverridden(langId) && langConfig.comments?.blockComment) {
+				langConfig.comments.blockComment = [
+					this.getOverriddenMultiLineComment(langId),
+					langConfig.comments.blockComment[1]
+				];
 			}
 
 			/**
@@ -1017,16 +1067,10 @@ export class Configuration {
 		logger.debug("The language configs found are:", this.languageConfigs);
 
 		// Multi-line language definitions.
-		logger.debug(
-			"The supported languages for multi-line blocks:",
-			utils.readJsonFile<MultiLineLanguageDefinitions>(this.multiLineLangDefinitionFilePath)
-		);
+		logger.debug("The supported languages for multi-line blocks:", this.getMultiLineLanguageDefinitions());
 
 		// Single-line language definitions.
-		logger.debug(
-			"The supported languages for single-line blocks:",
-			utils.readJsonFile<SingleLineLanguageDefinitions>(this.singleLineLangDefinitionFilePath)
-		);
+		logger.debug("The supported languages for single-line blocks:", this.getSingleLineLanguageDefinitions());
 	}
 
 	/**

src/extension.ts

@@ -32,6 +32,11 @@ export function activate(context: vscode.ExtensionContext) {
 	const extensionName = extensionData.get("namespace");
 	const extensionDisplayName = extensionData.get("displayName");
 
+	// In development mode, write language definitions to JSON files for debugging/reference.
+	if (context.extensionMode !== vscode.ExtensionMode.Production) {
+		configuration.writeCommentLanguageDefinitionsToJsonFile();
+	}
+
 	// Store disposables for cleanup
 	const disposables: vscode.Disposable[] = [];
 	let commentBlocksDisposables: vscode.Disposable[] = [];
@@ -75,21 +80,39 @@ export function activate(context: vscode.ExtensionContext) {
 			logger.setLogLevel(logLevel);
 		}
 
-		// Settings that require an extension host reload when changed.
-		const reloadRequiredSettings = [
-			"disabledLanguages",
-			"overrideDefaultLanguageMultiLineComments",
+		/**
+		 * Automatically update (without extension host reload) language definitions and
+		 * reconfigure the comment blocks when any of the following settings are changed.
+		 */
+		const languageSettings = [
 			"multiLineStyleBlocks",
 			"slashStyleBlocks",
 			"hashStyleBlocks",
 			"semicolonStyleBlocks",
+			"disabledLanguages",
+			"overrideDefaultLanguageMultiLineComments",
 		];
 
-		// Settings that require extension host reload
-		for (const setting of reloadRequiredSettings) {
+		for (const setting of languageSettings) {
 			if (event.affectsConfiguration(`${extensionName}.${setting}`)) {
-				showReloadMessage(extensionName, setting);
-				break; // Only show one reload message at a time
+				logger.info(`Configuration setting ${extensionName}.${setting} has changed.`);
+				// Dispose of old comment block configurations to prevent memory leaks
+				commentBlocksDisposables.forEach((disposable) => disposable.dispose());
+				commentBlocksDisposables = [];
+
+				configuration.updateLanguageDefinitions();
+
+				// In development mode, write updated language definitions to JSON files.
+				if (context.extensionMode !== vscode.ExtensionMode.Production) {
+					configuration.writeCommentLanguageDefinitionsToJsonFile();
+				}
+
+				commentBlocksDisposables = configuration.configureCommentBlocks();
+				disposables.push(...commentBlocksDisposables);
+
+				logger.info("Comment block configurations have been updated.");
+
+				break; // Only update once per change
 			}
 		}
 	});
@@ -132,21 +155,3 @@ export function activate(context: vscode.ExtensionContext) {
 export function deactivate() {
 	logger.disposeLogger();
 }
-
-/**
- * Shows a message prompting the user to reload the extension host.
- * @param extensionName The namespace of the extension
- * @param settingName The name of the setting that was changed
- */
-function showReloadMessage(extensionName: string, settingName: string): void {
-	vscode.window
-		.showInformationMessage(
-			`The ${extensionName}.${settingName} setting has been changed. Please reload the Extension Host to take effect.`,
-			"Reload"
-		)
-		.then((selection) => {
-			if (selection === "Reload") {
-				vscode.commands.executeCommand("workbench.action.restartExtensionHost");
-			}
-		});
-}

tsconfig.json

@@ -8,5 +8,8 @@
 		"rootDir": ".",
 		"typeRoots": ["./node_modules/@types"]
 	},
+	"typeAcquisition": {
+		"enable": true,
+	},
 	"exclude": ["node_modules", ".vscode-test"]
 }