configure_vscode.py

"""
Description:
  This script configures project-level VSCode settings in '.vscode/settings.json' for
  development and installs recommended extensions from '.vscode/extensions.json'.

Usage:
  python3 ./scripts/configure_vscode.py
"""
# pylint: disable=missing-function-docstring

import os
import json
from pathlib import Path
import subprocess
import sys
import re
from typing import Any, Optional
from shutil import which

VSCODE_SETTINGS_JSON_FILE: str = '.vscode/settings.json'
VSCODE_EXTENSIONS_JSON_FILE: str = '.vscode/extensions.json'

def main() -> None:
    ensure_vscode_directory_exists()
    ensure_setting_file_exists()
    add_or_update_settings()
    install_recommended_extensions()

def ensure_vscode_directory_exists() -> None:
    vscode_directory_path = os.path.dirname(VSCODE_SETTINGS_JSON_FILE)
    try:
        os.makedirs(vscode_directory_path, exist_ok=True)
        print_success(f"Created or verified directory: {vscode_directory_path}")
    except OSError as error:
        print_error(f"Error handling directory {vscode_directory_path}: {error}")

def ensure_setting_file_exists() -> None:
    try:
        if os.path.isfile(VSCODE_SETTINGS_JSON_FILE):
            print_success(f"VSCode settings file exists: {VSCODE_SETTINGS_JSON_FILE}")
            return
        with open(VSCODE_SETTINGS_JSON_FILE, 'w', encoding='utf-8') as file:
            json.dump({}, file, indent=4)
            print_success(f"Created empty {VSCODE_SETTINGS_JSON_FILE}")
    except IOError as error:
        print_error(f"Error creating file {VSCODE_SETTINGS_JSON_FILE}: {error}")
    print_success(f"Created empty {VSCODE_SETTINGS_JSON_FILE}")

def add_or_update_settings() -> None:
    configure_setting_key('eslint.validate', ['vue', 'javascript', 'typescript'])
    # Set ESLint validation for specific file types.
    # Details: # pylint: disable-next=line-too-long
    #   - https://web.archive.org/web/20230801024405/https://eslint.vuejs.org/user-guide/#visual-studio-code

    configure_setting_key('terminal.integrated.env.linux', {"GTK_PATH": ""})
    # Unset GTK_PATH on Linux for Electron development in sandboxed environments
    # like Snap or Flatpak VSCode installations, enabling script execution.
    # Details: # pylint: disable-next=line-too-long
    #   - https://archive.ph/2024.01.06-003914/https://github.com/microsoft/vscode/issues/179274, https://web.archive.org/web/20240106003915/https://github.com/microsoft/vscode/issues/179274

    # Disable telemetry
    configure_setting_key('redhat.telemetry.enabled', False)
    configure_setting_key('gitlens.telemetry.enabled', False)

def configure_setting_key(configuration_key: str, desired_value: Any) -> None:
    try:
        with open(VSCODE_SETTINGS_JSON_FILE, 'r+', encoding='utf-8') as file:
            settings: dict = json.load(file)
            if configuration_key in settings:
                actual_value = settings[configuration_key]
                if actual_value == desired_value:
                    print_skip(f"Already configured as desired: \"{configuration_key}\"")
                    return
            settings[configuration_key] = desired_value
            file.seek(0)
            json.dump(settings, file, indent=4)
            file.truncate()
        print_success(f"Added or updated configuration: {configuration_key}")
    except json.JSONDecodeError:
        print_error(f"Failed to update JSON for key {configuration_key}.")

def install_recommended_extensions() -> None:
    if not os.path.isfile(VSCODE_EXTENSIONS_JSON_FILE):
        print_error(
            f"The extensions.json file does not exist in the path: {VSCODE_EXTENSIONS_JSON_FILE}."
        )
        return
    with open(VSCODE_EXTENSIONS_JSON_FILE, 'r', encoding='utf-8') as file:
        json_content: str = remove_json_comments(file.read())
    try:
        data: dict = json.loads(json_content)
        extensions: list[str] = data.get("recommendations", [])
        if not extensions:
            print_skip(f"No recommendations found in the {VSCODE_EXTENSIONS_JSON_FILE} file.")
            return
        vscode_cli_path = locate_vscode_cli()
        if vscode_cli_path is None:
            print_error('Visual Studio Code CLI (`code`) tool not found.')
            return
        install_vscode_extensions(vscode_cli_path, extensions)
    except json.JSONDecodeError:
        print_error(f"Invalid JSON in {VSCODE_EXTENSIONS_JSON_FILE}")

def locate_vscode_cli() -> Optional[str]:
    vscode_alias = which('code') # More reliable than using `code`, especially on Windows.
    if vscode_alias:
        return vscode_alias
    potential_vscode_cli_paths = [
        # VS Code on macOS may not register 'code' command in PATH
        '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code'
    ]
    for vscode_cli_candidate_path in potential_vscode_cli_paths:
        if Path(vscode_cli_candidate_path).is_file():
            return vscode_cli_candidate_path
    return None

def remove_json_comments(json_like: str) -> str:
    pattern: str = r'(?:"(?:\\.|[^"\\])*"|/\*[\s\S]*?\*/|//.*)|([^:]//.*$)'
    return re.sub(
        pattern,
        lambda m: '' if m.group(1) else m.group(0), json_like, flags=re.MULTILINE,
    )

def install_vscode_extensions(vscode_cli_path: str, extensions: list[str]) -> None:
    successful_installations = 0
    for ext in extensions:
        try:
            result = subprocess.run(
                [vscode_cli_path, "--install-extension", ext],
                check=True,
                capture_output=True,
                text=True,
            )
            if "already installed" in result.stdout:
                print_skip(f"Created or verified directory: {ext}")
            else:
                print_success(f"Installed extension: {ext}")
            successful_installations += 1
            print_subprocess_output(result)
        except subprocess.CalledProcessError as e:
            print_subprocess_output(e)
            print_error(f"Failed to install extension: {ext}")
        except FileNotFoundError:
            print_error(' '.join([
                f"Visual Studio Code CLI tool not found: {vscode_cli_path}."
                f"Could not install extension: {ext}",
            ]))
        except Exception as e: # pylint: disable=broad-except
            print_error(' '.join([
                f"Failed to install extension '{ext}'.",
                f"Attempted using Visual Studio Code CLI at: '{vscode_cli_path}'.",
                f"Encountered error: {e}",
            ]))
    total_extensions = len(extensions)
    print_installation_results(successful_installations, total_extensions)

def print_subprocess_output(result: subprocess.CompletedProcess[str]) -> None:
    output = '\n'.join([text.strip() for text in [result.stdout, result.stderr] if text])
    if not output:
        return
    formatted_output = '\t' + output.strip().replace('\n', '\n\t')
    print(formatted_output)

def print_installation_results(successful_installations: int, total_extensions: int) -> None:
    if successful_installations == total_extensions:
        print_success(
            f"Successfully installed or verified all {total_extensions} recommended extensions."
        )
    elif successful_installations > 0:
        print_warning(
            f"Partially successful: Installed or verified {successful_installations} "
            f"out of {total_extensions} recommended extensions."
        )
    else:
        print_error("Failed to install any of the recommended extensions.")

def print_error(message: str) -> None:
    print(f"[ERROR] {message}", file=sys.stderr)

def print_success(message: str) -> None:
    print(f"[SUCCESS] {message}")

def print_skip(message: str) -> None:
    print(f"[SKIPPED] {message}")

def print_warning(message: str) -> None:
    print(f"[WARNING] {message}", file=sys.stderr)

if __name__ == "__main__":
    main()