fix: introduce proper typing for json objects.

- Added proper typings for json objects.
    - `JsonObject` interface to define a generic json object.
    - `JsonValue` type to define the possible types of the json values.
    - `JsonArray` type to define an array in json.

- Added interfaces to define the single-line and multi-line language definitions, which extend the `JsonObject`: `SingleLineLanguageDefinitions` and `MultiLineLanguageDefinitions`.

- Refactored `readJsonFile` util function to use the new `JsonObject` interface and `JsonValue` type. The function now passes a generic type `T` as it's return value, if the generic type isn't defined when calling the function, then it defaults to `JsonObject`. This ensures that specific types or interfaces can be defined as the return type that naturally is or extends a `JsonObject`. Eg. `readJsonFile<IPackageJson>()`.

- Refactored `writeJsonFile` util function to pass a generic type `T` as it's return value and it's `data` param type as `T`.

- Changed `obj` param type in `reconstructRegex` util function to `unknown.

- Changed `convertMapToReversedObject` util function return type to `JsonObject`.

- Changed `readJsonFile` function call in `ExtensionData::getExtensionPackageJsonData` method to define the generic return type as `IPackageJson`.

- Changed `Configuration::getLanguagesToSkip` method return type to `JsonArray`.

- Refactored `Configuration::writeCommentLanguageDefinitionsToJsonFile` method to properly type the code as the new `MultiLineLanguageDefinitions` and `SingleLineLanguageDefinitions` interfaces.

- Changed `defaultMultiLineConfig` variable in  `Configuration::setLanguageConfiguration` to be cast as `vscode.LanguageConfiguration` to ensure the `readJsonFile` return type is of that type.

- Auto-formatting changes., like removal of commas.

- Changed the `readJsonFile` function call return type in `Configuration::logDebugInfo` method to use the `MultiLineLanguageDefinitions` and `SingleLineLanguageDefinitions` interfaces.

Author: yCodeTech

src/configuration.ts

@@ -14,6 +14,8 @@ import {ExtensionData} from "./extensionData";
 import {Settings} from "./interfaces/settings";
 import {LineComment, SingleLineCommentStyle} from "./interfaces/commentStyles";
 import {ExtensionMetaData} from "./interfaces/extensionMetaData";
+import {MultiLineLanguageDefinitions, SingleLineLanguageDefinitions} from "./interfaces/utils";
+import {JsonArray} from "./interfaces/utils";
 
 export class Configuration {
 	/**************
@@ -167,7 +169,7 @@ export class Configuration {
 			"auto-comment-blocks.changeBladeMultiLineBlock",
 			(textEditor, edit, args) => {
 				this.handleChangeBladeMultiLineBlock(textEditor);
-			},
+			}
 		);
 		return [singleLineBlockCommand, changeBladeMultiLineBlockCommand];
 	}
@@ -294,11 +296,11 @@ export class Configuration {
 	 *
 	 * Idea from this StackOverflow answer https://stackoverflow.com/a/72988011/2358222
 	 *
-	 * @returns {string[]}
+	 * @returns {JsonArray}
 	 */
-	private getLanguagesToSkip(): string[] {
+	private getLanguagesToSkip(): JsonArray {
 		const json = utils.readJsonFile(`${__dirname}/../../config/skip-languages.jsonc`);
-		return json.languages;
+		return json.languages as JsonArray;
 	}
 
 	/**
@@ -671,10 +673,16 @@ export class Configuration {
 		// Ensure the auto-generated directory exists.
 		utils.ensureDirExists(this.autoGeneratedDir);
 
-		// Write the into the single-line-languages.json file.
-		utils.writeJsonFile(this.singleLineLangDefinitionFilePath, utils.convertMapToReversedObject(this.singleLineBlocksMap));
-		// Write the into the multi-line-languages.json file.
-		utils.writeJsonFile(this.multiLineLangDefinitionFilePath, Object.fromEntries(this.multiLineBlocksMap));
+		// Convert the singleLineBlocksMap to an object.
+		const singleLineData = utils.convertMapToReversedObject(this.singleLineBlocksMap) as SingleLineLanguageDefinitions;
+
+		const multiLineData = Object.fromEntries(this.multiLineBlocksMap) as unknown as MultiLineLanguageDefinitions;
+
+		// Write into the single-line-languages.json file.
+		utils.writeJsonFile<SingleLineLanguageDefinitions>(this.singleLineLangDefinitionFilePath, singleLineData);
+
+		// Write into the multi-line-languages.json file.
+		utils.writeJsonFile<MultiLineLanguageDefinitions>(this.multiLineLangDefinitionFilePath, multiLineData);
 	}
 
 	/**
@@ -701,7 +709,7 @@ export class Configuration {
 	 */
 	private setLanguageConfiguration(langId: string, multiLine?: boolean, singleLineStyle?: string): vscode.Disposable {
 		const internalLangConfig: vscode.LanguageConfiguration = this.getLanguageConfig(langId);
-		const defaultMultiLineConfig: vscode.LanguageConfiguration = utils.readJsonFile(`${__dirname}/../../config/default-multi-line-config.json`);
+		const defaultMultiLineConfig = utils.readJsonFile(`${__dirname}/../../config/default-multi-line-config.json`) as vscode.LanguageConfiguration;
 
 		let langConfig = {...internalLangConfig};
 
@@ -956,7 +964,7 @@ export class Configuration {
 		else if (langId == "blade" && this.isLangIdDisabled(langId)) {
 			vscode.window.showInformationMessage(
 				`Blade is set as disabled in the "${extensionName}.disabledLanguages" setting. The "${extensionName}.bladeOverrideComments" setting will have no affect.`,
-				"OK",
+				"OK"
 			);
 
 			// Set the comments for blade language.
@@ -1011,8 +1019,14 @@ export class Configuration {
 		// Log the objects for debugging purposes.
 		logger.debug("The language config filepaths found are:", this.languageConfigFilePaths);
 		logger.debug("The language configs found are:", this.languageConfigs);
-		logger.debug("The supported languages for multi-line blocks:", utils.readJsonFile(this.multiLineLangDefinitionFilePath));
-		logger.debug("The supported languages for single-line blocks:", utils.readJsonFile(this.singleLineLangDefinitionFilePath));
+		logger.debug(
+			"The supported languages for multi-line blocks:",
+			utils.readJsonFile<MultiLineLanguageDefinitions>(this.multiLineLangDefinitionFilePath)
+		);
+		logger.debug(
+			"The supported languages for single-line blocks:",
+			utils.readJsonFile<SingleLineLanguageDefinitions>(this.singleLineLangDefinitionFilePath)
+		);
 	}
 
 	/**

src/extensionData.ts

@@ -61,7 +61,7 @@ export class ExtensionData {
 	private getExtensionPackageJsonData(): IPackageJson | null {
 		// Get the package.json file path.
 		const packageJSONPath = path.join(this.extensionPath, "package.json");
-		return readJsonFile(packageJSONPath, false);
+		return readJsonFile<IPackageJson>(packageJSONPath, false);
 	}
 
 	/**

src/interfaces/utils.ts

@@ -0,0 +1,34 @@
+import {SingleLineCommentStyle} from "./commentStyles";
+
+/**
+ * Represents a JSON object.
+ */
+export interface JsonObject {
+	[key: string]: JsonValue;
+}
+
+/**
+ * Represents a valid JSON value.
+ */
+export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
+
+/**
+ * Represents a JSON array.
+ */
+export type JsonArray = JsonValue[] | readonly JsonValue[];
+
+/**
+ * Structure for single-line language definitions JSON file
+ */
+export interface SingleLineLanguageDefinitions extends JsonObject {
+	supportedLanguages: Record<SingleLineCommentStyle, string[]>;
+	customSupportedLanguages: Record<SingleLineCommentStyle, string[]>;
+}
+
+/**
+ * Structure for multi-line language definitions JSON file
+ */
+export interface MultiLineLanguageDefinitions extends JsonObject {
+	supportedLanguages: string[];
+	customSupportedLanguages: string[];
+}

src/utils.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as jsonc from "jsonc-parser";
 import {logger} from "./logger";
 import {window} from "vscode";
+import {JsonObject, JsonValue} from "./interfaces/utils";
 
 /**
  * Read the file and parse the JSON.
@@ -10,10 +11,11 @@ import {window} from "vscode";
  * @param {boolean} [throwOnFileMissing=true] Whether to throw an error if the file doesn't exist.
  * If `false`, returns `null`. Default is `true`.
  *
- * @returns {any | null} The JSON file content as an object, or `null` if file doesn't exist and `throwOnFileMissing` is `false`.
+ * @returns {T | null} The JSON file content as the passed T type (defaulting to a JSON object)
+ * or `null` if file doesn't exist and `throwOnFileMissing` is `false`.
  * @throws Will throw an error if the JSON file cannot be parsed or if file doesn't exist and `throwOnFileMissing` is `true`.
  */
-export function readJsonFile(filepath: string, throwOnFileMissing: boolean = true): any | null {
+export function readJsonFile<T extends JsonValue = JsonObject>(filepath: string, throwOnFileMissing: boolean = true): T | null {
 	// Check if file exists first.
 	// If file doesn't exist...
 	if (!fs.existsSync(filepath)) {
@@ -46,7 +48,7 @@ export function readJsonFile(filepath: string, throwOnFileMissing: boolean = tru
 			.showErrorMessage(
 				`${errorMsg}. The extension cannot continue. Please check the "Auto Comment Blocks" Output Channel for errors.`,
 				"OK",
-				"Open Output Channel",
+				"Open Output Channel"
 			)
 			.then((selection) => {
 				if (selection === "Open Output Channel") {
@@ -57,7 +59,7 @@ export function readJsonFile(filepath: string, throwOnFileMissing: boolean = tru
 		throw error;
 	}
 
-	return jsonContents;
+	return jsonContents as T;
 }
 
 /**
@@ -94,10 +96,10 @@ function constructJsonParseErrorMsg(filepath: string, fileContent: string, jsonE
  * Read the file and parse the JSON.
  *
  * @param {string} filepath The path of the file.
- * @param {any} data The data to write into the file.
+ * @param {T} data The data to write into the file.
  * @returns The file content.
  */
-export function writeJsonFile(filepath: string, data: any): any {
+export function writeJsonFile<T>(filepath: string, data: T) {
 	// Write the updated JSON back into the file and add tab indentation
 	// to make it easier to read.
 	fs.writeFileSync(filepath, JSON.stringify(data, null, "\t"));
@@ -122,7 +124,7 @@ export function ensureDirExists(dir: string) {
  * @param key The key to check in the object
  * @returns {RegExp} The reconstructed regex pattern.
  */
-export function reconstructRegex(obj: any, key: string) {
+export function reconstructRegex(obj: unknown, key: string) {
 	// If key has a "pattern" key, then it's an object...
 	if (Object.hasOwn(obj[key], "pattern")) {
 		return new RegExp(obj[key].pattern);
@@ -139,7 +141,7 @@ export function reconstructRegex(obj: any, key: string) {
  * Code based on this StackOverflow answer https://stackoverflow.com/a/45728850/2358222
  *
  * @param {Map<string, Map<string, string>>} m The Map to convert to an object.
- * @returns {object} The converted object.
+ * @returns {JsonObject} The converted object.
  *
  * @example
  * reverseMapping(
@@ -165,8 +167,8 @@ export function reconstructRegex(obj: any, key: string) {
  * 	}
  * }
  */
-export function convertMapToReversedObject(m: Map<string, Map<string, string>>): object {
-	const result: any = {};
+export function convertMapToReversedObject(m: Map<string, Map<string, string>>): JsonObject {
+	const result: JsonObject = {};
 
 	// Convert a nested key:value Map from inside another Map into an key:array object,
 	// while reversing/switching the keys and values. The Map's values are now the keys of