ZedScripts 0.0.2__py3-none-any.whl

ZedScripts/environment/workspace.py

@@ -0,0 +1,320 @@
+import logging
+import json
+import re
+from pathlib import Path
+from typing import Any, TYPE_CHECKING, Iterable
+from pydantic import ValidationError
+
+
+from .. import CONFIGURATION_FILE_NAME, GLOBAL_CONFIGURATION_FILE
+from . import WorkspaceType, VersionType
+from .document import Document
+from .mod import Mod, ModCollection
+from .version import Version
+from .config import ConfigurationModel
+from ..providers.notifications import ZedNotification, send_progress_notification
+from ..utils import merge_pydantic_models
+from ..scripts.dataset import Dataset
+
+if TYPE_CHECKING:
+    from ..scripts.block import ScriptBlock
+
+
+
+class Workspace:
+    workspace_cache: dict[WorkspaceType, dict[Path, 'Workspace']] = {}
+    global_configuration: ConfigurationModel | None = None
+    global_dataset: 'Dataset' = Dataset()
+
+    def __init__(self, folder: Path, workspace_type: WorkspaceType):
+        self.folder = folder
+        self.workspace_type = workspace_type
+        self.documents: dict[Path, Document] = {}
+
+        self.mods: ModCollection = ModCollection()
+        self.ignored_patterns: list[re.Pattern] = []
+        self.configuration: ConfigurationModel = self.update_configuration()
+        self.dataset: Dataset = Dataset()
+        self.dataset.load(self.configuration.dataset)
+
+        # cache workspace
+        Workspace.workspace_cache.setdefault(workspace_type, {})[folder] = self
+
+    def __repr__(self) -> str:
+        return f"Workspace(type={self.workspace_type}, folder={self.folder})"
+
+    def load(self) -> None:
+        """
+        Retrieve every script files and cache them as Document instances.
+        """
+        logging.info(f"Loading workspace: {self.folder}")
+        self.load_mods()
+        # self.load_documents()
+        self.load_documents()
+
+    def load_documents(self) -> None:
+        send_progress_notification(ZedNotification.LOADING_DOCUMENTS, 
+                                   self.folder, 0.0, self.workspace_type)
+
+        # inside the workspace folder, find every txt files, and try to load them
+        # as documents
+        files = list(self.folder.rglob("*.txt"))
+        total_files = len(files)
+        last_progress = 0
+        step = 10
+        step_count = step * total_files / 100
+        for progress, path in enumerate(files):
+            self.load_document(path)
+
+            # send update notification to client
+            if progress - last_progress >= step_count:
+                logging.info(f"Loading progress: {progress}/{total_files}")
+                send_progress_notification(ZedNotification.LOADING_DOCUMENTS, 
+                                           self.folder, progress / total_files * 100, self.workspace_type)
+                last_progress = progress
+
+        # send final progress notification
+        send_progress_notification(ZedNotification.LOADING_DOCUMENTS, 
+                                   self.folder, 100, self.workspace_type)
+
+    def load_mods(self) -> None:
+        logging.info(f"Loading mods for workspace: {self.folder}")
+        # look for mod.info files
+        # one or more of these files are associated to a specific mod
+        for file in self.folder.rglob("mod.info"):
+            # only consider versioning and common folders
+            version = Version.find_or_make_version(file)
+            if version.type in {VersionType.VERSIONING, VersionType.COMMON}:
+                mod_folder = file.parent.parent
+                mod = Mod.find_or_make_mod(mod_folder, self)
+                mod.add_mod_info_file(file, version)
+                self.mods[mod_folder] = mod
+                continue
+
+            # if it's OTHER, then it's probably not a mod file
+            # TODO: should we handle those ?
+
+    @staticmethod
+    def load_libraries() -> None:
+        logging.info("Loading libraries for all workspaces.")
+
+        # gather libraries from configs
+        config = Workspace.get_global_configuration()
+
+        configs = []
+        for workspace in Workspace.workspace_cache.get(WorkspaceType.PROJECT, {}).values():
+            configs.append(workspace.get_configuration())
+        merged_config = merge_pydantic_models(config, *configs)
+
+        # add each libraries to global library cache
+        libraries = merged_config.libraries
+        libraries = Workspace.filter_out_projects(libraries)
+
+        Workspace.workspace_cache[WorkspaceType.LIBRARY] = {}
+        for library in libraries:
+            Workspace.workspace_cache[WorkspaceType.LIBRARY][library] = Workspace(library, WorkspaceType.LIBRARY)
+        for library in Workspace.workspace_cache[WorkspaceType.LIBRARY].values():
+            library.load()
+
+    def should_ignore(self, path: Path) -> bool:
+        for pattern in self.ignored_patterns:
+            if pattern.search(str(path)):
+                return True
+        return False
+
+    def load_document(self, path: Path) -> Document | None:
+        # skip if the path respects the ignored patterns
+        if self.should_ignore(path):
+            return None
+
+        document = Document.find_or_make(self.dataset, path, self)
+        if document is not None:
+            self.mods.add_document(path, document)
+            self.documents[path] = document
+        return document
+
+
+    @staticmethod
+    def find_workspace(path: Path) -> 'Workspace | None':
+        for workspaces in Workspace.workspace_cache.values():
+            for folder, workspace in workspaces.items():
+                if folder in path.parents:
+                    return workspace
+        return None
+
+    @staticmethod
+    def find_or_make(path: Path) -> Document | None:
+        # find the document with the associated path
+        docs = Document.list_by_workspace()
+        for doc in docs.keys():
+            if doc.path == path:
+                return doc
+
+        workspace = Workspace.find_workspace(path)
+        if workspace is not None:
+            return workspace.load_document(path)
+        return None
+
+    @staticmethod
+    def filter_out_projects(libraries: set[Path]) -> set[Path]:
+        """Filter out the libraries that are already present inside 
+        folders of project workspaces since those will have already parsed that content.
+        
+        Doesn't filter out libraries that are a folder above a project workspace however."""
+        project_folders = set(Workspace.workspace_cache.get(WorkspaceType.PROJECT, {}).keys())
+        
+        return {lib for lib in libraries 
+                if not any(lib.resolve().is_relative_to(proj.resolve()) 
+                           for proj in project_folders)}
+
+
+# searches
+
+    @staticmethod
+    def search_for_block_references(version: Version, modules: Iterable[str], 
+                                    id: str, block_type: str) -> list['ScriptBlock']:
+        """Searches for block references within the specified modules and version context.
+
+        Args:
+            version (Version): The version context for the search.
+            modules (Iterable[str]): List of module names to search within.
+            id (str): ID of the block to search for.
+            block_type (str): Expected type of the block to search for.
+        """
+        result: set['ScriptBlock'] = set()
+
+        # skip search for pre B42 versions
+        if version == Version.PRE_42:
+            return list(result)
+
+        # search into documents with a version that is general
+        versions = [Version.COMMON, Version.BASE_GAME, Version.OTHER]
+        documents = [doc for v in versions for doc in Document.documents_by_version.get(v, [])]
+        for document in documents:
+            if document.body is None: continue
+            refs = document.body.find_references(modules, id, block_type)
+            result.update(refs)
+
+        # iterate over each mods, and look for the closest 
+        # version to the version we are looking into for each
+        # to look for references
+        for workspaces in Workspace.workspace_cache.values():
+            for workspace in workspaces.values():
+                for mod in workspace.mods.values():
+                    for document in mod.documents.values():
+                        if document.body is None: continue
+                        refs = document.body.find_references(modules, id, block_type)
+                        result.update(refs)
+
+        return list(result)
+
+
+
+
+# configuration
+
+    @staticmethod
+    def find_workspace_of_configuration_file(path: Path) -> 'Workspace | None':
+        # only search in project workspaces
+        for workspace in Workspace.workspace_cache.get(WorkspaceType.PROJECT, {}).values():
+            if (workspace.get_configuration_path() == path):
+                return workspace
+        return None
+
+    @staticmethod
+    def is_configuration_file(path: Path) -> bool:
+        return path.is_file() and path.name == CONFIGURATION_FILE_NAME
+
+    @staticmethod
+    def is_global_configuration_file(path: Path) -> bool:
+        return path.is_file() and path.resolve() == GLOBAL_CONFIGURATION_FILE
+
+    @staticmethod
+    def update_global_configuration(text: str | None = None) -> None:
+        logging.info("Updating global configuration from %s", GLOBAL_CONFIGURATION_FILE)
+        Workspace.global_configuration = Workspace.load_configuration(GLOBAL_CONFIGURATION_FILE, text=text)
+        logging.debug(Workspace.global_configuration)
+
+    @staticmethod
+    def update_configuration_file(path: Path, text: str | None = None) -> bool:
+        # skip if not a configuration file
+        if not Workspace.is_configuration_file(path):
+            return False
+
+        # check if it's a global config file
+        if Workspace.is_global_configuration_file(path):
+            Workspace.update_global_configuration()
+            return True
+
+        # find out if it's a workspace-relative config file
+        workspace = Workspace.find_workspace_of_configuration_file(path)
+        if workspace is None:
+            return False
+
+        # if it's from a workspace, then we simply update its configuration
+        workspace.update_configuration(text=text)
+        return True
+
+    @staticmethod
+    def update_all_configurations() -> None:
+        Workspace.update_global_configuration()
+        for workspace in Workspace.workspace_cache.get(WorkspaceType.PROJECT, {}).values():
+            workspace.update_configuration()
+
+    def get_configuration_path(self) -> Path:
+        return self.folder / CONFIGURATION_FILE_NAME
+
+    def update_configuration(self, text: str | None = None) -> ConfigurationModel:
+        logging.info("Updating configuration for workspace at %s", self.folder)
+        self.configuration = Workspace.load_configuration(self.get_configuration_path(), text=text)
+        logging.debug(self.configuration)
+        self.post_update_configuration()
+        return self.configuration
+
+    def post_update_configuration(self) -> None:
+        ignored = self.get_configuration().ignored
+        self.ignored_patterns = [re.compile(pattern) for pattern in ignored]
+
+    @staticmethod
+    def get_global_configuration() -> ConfigurationModel:
+        if Workspace.global_configuration is None:
+            Workspace.update_global_configuration()
+        assert Workspace.global_configuration is not None # to make Pylance happy
+        return Workspace.global_configuration
+
+    def get_configuration(self) -> ConfigurationModel:
+        if self.configuration is None:
+            self.update_configuration()
+        assert self.configuration is not None # to make Pylance happy
+
+        # merge with global configuration
+        global_config = Workspace.get_global_configuration()
+
+        return merge_pydantic_models(global_config, self.configuration)
+
+    @staticmethod
+    def load_configuration(config_path: Path, text: str | None = None) -> ConfigurationModel:
+        if not config_path.exists() or not config_path.is_file():
+            return ConfigurationModel()
+
+        # load the configuration file
+        try:
+            if text is not None:
+                data = json.loads(text)
+            else:
+                with open(config_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError) as e:
+            logging.exception(f"Failed to load configuration file {config_path}. Loading default configuration.")
+            return ConfigurationModel()
+
+        try:
+            # only validate a configuration file that is already a dictionary
+            if isinstance(data, dict):
+                return ConfigurationModel.model_validate(data)
+
+            logging.warning(f"Configuration file {config_path} should contain a dictionary as the root. Loading default configuration.")
+            return ConfigurationModel()
+        except ValidationError as e:
+            logging.warning(f"Configuration file validation error for {config_path}:\n{e}")
+            return ConfigurationModel()

ZedScripts/locale/en.json

@@ -0,0 +1,38 @@
+{
+    "code": "en",
+    "strings": {
+        "PARSER_TOO_MANY_CLOSING_BRACKETS": "Too many closing brackets.",
+        "PARSER_BLOCK_MISSING_TYPE": "Block is missing a type.",
+        "PARSER_BLOCK_NOT_CLOSED": "Block not closed.",
+        "PARSER_UNPARSED_TOKENS": "Unparsed tokens found.",
+
+        "BLOCK_UNKNOWN_BLOCK": "'{type}' is an unknown script block.",
+
+        "BLOCK_UNEXPECTED_ID": "'{type}' block cannot have an ID ('{id}').",
+        "BLOCK_MISSING_ID": "'{type}' block is missing an ID.",
+        "BLOCK_HAS_ID_IN_PARENT": "'{type}' block cannot have an ID when inside parent block '{parent_type}', only for: {invalid_blocks}.",
+        "BLOCK_ID_CANNOT_CONTAIN_SPACES": "ID '{id}' for block '{type}' cannot contain spaces.",
+        "BLOCK_INVALID_ID": "'{type}' block has an invalid ID '{id}'. Valid IDs are: {validIDs}.",
+        "BLOCK_FORBIDDEN_ID": "'{type}' block has a forbidden ID '{id}'. Forbidden IDs are: {forbiddenIDs}.",
+
+        "VALUE_UNKNOWN_PARAMETER": "Unknown parameter '{key}' in block '{type}'.",
+        "VALUE_DEPRECATED_REPLACEMENT_VERSION": "This parameter is deprecated since version '{version}' and replaced by '{replacement}'. {description}",
+        "VALUE_DEPRECATED_REPLACEMENT": "This parameter is deprecated and replaced by '{replacement}'. {description}",
+        "VALUE_DEPRECATED_VERSION": "This parameter is deprecated since version '{version}'. {description}",
+        "VALUE_DEPRECATED": "This parameter is deprecated. {description}",
+        "VALUE_DUPLICATE": "Duplicate parameter '{key}' in block '{type}'.",
+        "VALUE_MISSING": "Parameter '{key}' is missing a value in block '{type}'.",
+        "VALUE_FORBIDDEN": "Parameter '{key}' in block '{type}' has forbidden values: {forbidden_values}. Allowed values are: {accepted_values}.",
+        "VALUE_INVALID_TYPE": "Type '{actual_type}' of '{key}' is invalid for value '{value}'. Expected type is '{expected_type}'.",
+        "VALUE_INVALID_OBJECT_FORMAT": "Values {values} for parameter '{key}' do not follow the expected 'key{key_value_separator}value' format.",
+        "VALUE_INVALID_OBJECT_KEY_TYPE": "Key '{obj_key}' for parameter '{key}' is of invalid type '{actual_type}'. Expected type is '{expected_type}'.",
+        "VALUE_INVALID_OBJECT_VALUE_TYPE": "Value '{obj_value}' for parameter '{key}' is of invalid type '{actual_type}'. Expected type is '{expected_type}'.",
+        "VALUE_WRONGLY_FORMATTED_KEY_VALUE_PAIR": "Parameter '{key}' in block '{type}' with value '{value}' is likely wrongly formatted. Verify you're not missing a comma or you're not using the '=' symbol incorrectly.",
+        "VALUE_WITH_NEWLINE": "Parameter '{key}' in block '{type}' has a newline in its value '{value}'. This is usually the symptom of a missing comma.",
+        "VALUE_INVALID_BLOCK_REFERENCE": "Value '{value}' has a wrongly formatted block reference. Expected format is 'module.block' or 'block'.",
+        "VALUE_CANNOT_PROVIDE_MODULE": "Value '{value}' cannot contain a module '{module}' reference, only direct block references are allowed.",
+        "VALUE_BLOCK_REF_CANNOT_BE_EMPTY": "Value '{value}' has an empty block reference, which is not allowed.",
+        "VALUE_UNMATCHED_BLOCK_REF": "Value '{value}' for parameter '{parameter}' does not match any existing block (expects '{expected_block}' block). Make sure the referenced block exists.",
+        "VALUE_MULTIPLE_BLOCK_REFS": "Multiple block references found for '{value}' for parameter '{parameter}' (expects '{expected_block}' block). Make sure duplicate block references are not present."
+    }
+}

ZedScripts/main.py

@@ -0,0 +1,7 @@
+from ZedScripts.server import zedserver
+
+def main() -> None:
+    zedserver.startup()
+
+if __name__ == "__main__":
+    main()

ZedScripts/providers/actions.py

@@ -0,0 +1,13 @@
+from lsprotocol import types
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from ..structure.lexer import TextRange
+
+def make_linked_editing_ranges(ranges: list['TextRange']) -> types.LinkedEditingRanges:
+    # remove duplicate ranges
+    ranges = list(set(ranges))
+    
+    # convert TextRange to types.Range
+    r = [range.to_lsp() for range in ranges]
+    return types.LinkedEditingRanges(ranges=r)

ZedScripts/providers/capabilities.py

@@ -0,0 +1,107 @@
+r"""
+Provides client and server capabilities tools
+"""
+
+import logging
+
+from lsprotocol import types
+
+from .semantic_tokens import get_tokens
+
+_client_init: types.InitializeParams | None
+
+def register_client_capabilities(params: types.InitializeParams):
+    global _client_init
+    _client_init = params
+
+    logging.info("Registering client capabilities")
+
+    client_info = params.client_info
+    if client_info is not None:
+        logging.info("Client info: %s %s", client_info.name, client_info.version)
+    else:
+        logging.info("Client info is not available")
+
+
+
+
+## CLIENT CAPABILITIES
+
+def get_diagnostics_capabilities() -> types.DiagnosticClientCapabilities | None:
+    """
+    
+    """
+    assert _client_init is not None, "Client has not been initialized"
+
+    client_init = _client_init
+    client_capabilities = client_init.capabilities
+    text_document = client_capabilities.text_document
+
+    if text_document is None:
+        return None
+
+    return text_document.diagnostic
+
+def is_support_pull_diagnostics() -> bool:
+    """
+    Whenever pull mode for diagnostics is possible. It was added in 
+    LSP 3.17 and VSCode's language server node package as of 09-2026
+    is at LSP 3.18.3 so some clients may not support it, simply for
+    other IDEs that don't get too many updates.
+    """
+    return get_diagnostics_capabilities() is not None
+
+
+
+
+## SERVER CAPABILITIES
+
+def get_server_capabilities() -> types.ServerCapabilities:
+    """
+    Below are the explanation for diagnostics
+
+    ### Diagnostics
+    Our diagnostics depend on other files so we prefer to diagnostic 
+    the whole workspace. 
+    They could take a while for large workspaces (i.e. the game files) 
+    so we want to provide feedback when it takes a while.
+    Diagnostics in pull mode (diagnostic_provider != None) was only
+    introduced in LSP 3.17 and may not be supported by all clients.
+    """
+    # diagnostic support in pull mode
+    if is_support_pull_diagnostics():
+        diagnostic_provider = types.DiagnosticOptions(
+            inter_file_dependencies = True,
+            workspace_diagnostics   = True,
+            identifier              = "zedscripts",
+            work_done_progress      = True,
+        )
+    else:
+        diagnostic_provider = None
+
+    # for onChange capabilities, for the token reparsing
+    # we should look into the delta method
+    # added in LSP 3.18
+    # https://pygls.readthedocs.io/en/latest/pygls/api-reference/types.html#lsprotocol.types.DidChangeTextDocumentParams
+    # https://pygls.readthedocs.io/en/latest/pygls/api-reference/types.html#lsprotocol.types.SemanticTokensOptions.full
+    # so we update the lexical tokens accordingly
+    # to then update the semantic tokens
+    # and only change the parts of the document that have actually been modified
+
+    # for now, we just retokenize the whole document
+    token_types, token_modifiers = get_tokens()
+    logging.debug("Token types: %s", token_types)
+    logging.debug("Token modifiers: %s", token_modifiers)
+    semantic_tokens_provider = types.SemanticTokensOptions(
+        legend = types.SemanticTokensLegend(
+            token_types     = token_types,
+            token_modifiers = token_modifiers
+        ),
+        full               = True, # for deltas, we need to change that
+        work_done_progress = True,
+    )
+
+    return types.ServerCapabilities(
+        diagnostic_provider=diagnostic_provider,
+        semantic_tokens_provider=semantic_tokens_provider,
+    )

ZedScripts/providers/configuration.py

@@ -0,0 +1,26 @@
+import enum
+from typing import Any, TypedDict
+
+
+class ConfigurationType(enum.IntEnum):
+    DATA_SOURCE = enum.auto()
+
+# TODO: implement fixed configuration values
+
+
+default_configuration: dict[ConfigurationType, Any] = {
+    ConfigurationType.DATA_SOURCE: "latest"
+}
+
+
+
+class Configuration:
+    def __init__(self):
+        self.settings: dict[ConfigurationType, Any] = {}
+
+    def get(self, key: ConfigurationType, default=None):
+        return self.settings.get(key, default)
+
+    def set(self, key: ConfigurationType, value):
+        self.settings[key] = value
+

ZedScripts/providers/debug.py

@@ -0,0 +1,59 @@
+import socket
+import subprocess
+import sys
+import logging
+import time
+
+def is_port_available(port: int, host: str = "localhost", timeout: float = 0.5) -> bool:
+    """Check if a port is available by attempting to bind to it."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.settimeout(timeout)
+    try:
+        result = sock.connect_ex((host, port))
+        sock.close()
+        return result != 0  # Non-zero means port is not in use
+    except Exception:
+        return True
+
+
+def force_close_port(port: int) -> None:
+    """Force close any process using the specified port."""
+    try:
+        if sys.platform == "win32":
+            # Windows: use netstat and taskkill
+            subprocess.run(
+                f'netstat -ano | findstr ":{port}" | findstr "LISTENING"',
+                shell=True,
+                capture_output=True,
+                text=True,
+            )
+            # Alternative: use Get-Process on PowerShell
+            subprocess.run(
+                f'powershell -Command "Get-NetTCPConnection -LocalPort {port} -ErrorAction SilentlyContinue | Stop-Process -Force"',
+                shell=True,
+                capture_output=True,
+            )
+        else:
+            # Linux/Mac: use lsof or fuser
+            try:
+                subprocess.run(
+                    f"kill -9 $(lsof -t -i :{port})",
+                    shell=True,
+                    capture_output=True,
+                    timeout=2,
+                )
+                logging.debug(f"Forcefully closed port {port}")
+            except subprocess.TimeoutExpired:
+                logging.warning(f"Timeout while trying to close port {port}")
+    except Exception as e:
+        logging.debug(f"Could not force close port {port}: {e}")
+
+
+def wait_for_port_available(port: int, host: str = "localhost", max_retries: int = 10, retry_delay: float = 0.5) -> bool:
+    """Wait for a port to become available, with retries."""
+    for attempt in range(max_retries):
+        if is_port_available(port, host):
+            return True
+        logging.debug(f"Port {port} still in use, waiting... (attempt {attempt + 1}/{max_retries})")
+        time.sleep(retry_delay)
+    return False

ZedScripts/providers/diagnostics.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from lsprotocol.types import DiagnosticSeverity, DiagnosticTag
+
+import enum
+from typing import TYPE_CHECKING, ClassVar, Any
+from dataclasses import dataclass
+
+from lsprotocol import types
+
+import ZedScripts
+from ..utils import textrange_to_lsp
+from ..enums.SyntaxErrorType import SyntaxErrorType
+from ..structure.lexer import TextRange
+from ..providers.locale import zedlocalizer
+
+if TYPE_CHECKING:
+    from ..enums.Diagnostic import DiagnosticType
+
+type DiagnosticReport = (
+      types.UnchangedDocumentDiagnosticReport
+    | types.FullDocumentDiagnosticReport
+)
+"""Defines diagnostic report types to send to the client"""
+
+type WorkspaceDiagnosticReport = (
+      types.WorkspaceUnchangedDocumentDiagnosticReport
+    | types.WorkspaceFullDocumentDiagnosticReport
+)
+"""Defines workspace diagnostic report types to send to the client"""
+
+
+class DiagnosticDefinition:
+    by_type: ClassVar[dict[DiagnosticType, DiagnosticDefinition]] = {}
+
+    def __init__(self, 
+                 type: DiagnosticType, 
+                 severity: types.DiagnosticSeverity, 
+                 args: dict[str, Any] = {},
+                 tags: list[DiagnosticTag] = [],
+                ) -> None:
+        self.type: DiagnosticType = type
+        self.severity: types.DiagnosticSeverity = severity
+        self.args: dict[str, Any] = args
+        self.tags: list[DiagnosticTag] = tags
+
+        DiagnosticDefinition.by_type[type] = self
+
+    def get_name(self) -> str:
+        """Provides an identifier for the diagnostic type."""
+        return self.type.name
+
+
+@dataclass
+class DiagnosticInfo:
+    type: DiagnosticType
+    location: TextRange
+    args: dict[str, Any]
+
+
+class DiagnosticCollection(list[DiagnosticInfo]):
+    def to_lsp(self) -> list[types.Diagnostic]:
+        """
+        Converts the different diagnostic information into LSP-compatible diagnostics.
+
+        Returns:
+            list[types.Diagnostic]: A list of LSP-compatible diagnostic objects.
+        """
+        lsp_diagnostics: list[types.Diagnostic] = []
+        for diagnostic in self:
+            definition = DiagnosticDefinition.by_type[diagnostic.type]
+
+            # ensure that the correct arguments are always passed
+            for name, arg_type in definition.args.items():
+                assert name in diagnostic.args, f"Missing argument '{name}' for diagnostic '{definition.get_name()}'"
+                assert isinstance(diagnostic.args[name], arg_type), f"Argument '{name}' for diagnostic '{definition.get_name()}' must be of type '{arg_type.__name__}'"
+
+            lsp_diagnostics.append(
+                types.Diagnostic(
+                    range=textrange_to_lsp(diagnostic.location),
+                    message=zedlocalizer.localize_string(definition.type, definition,
+                                                                args=diagnostic.args),
+                    severity=definition.severity,
+                    source=ZedScripts.SOURCE,
+                    code=definition.get_name(),
+                    tags=definition.tags
+                )
+            )
+        return lsp_diagnostics
+
+    def add(self, type: DiagnosticType, location: TextRange, args: dict[str, Any] = {}) -> None:
+        """
+        Adds a new diagnostic to the collection.
+
+        Args:
+            type (DiagnosticType): The type of the diagnostic.
+            location (TextRange): The location in the text where the diagnostic applies.
+            args (dict[str, Any], optional): Additional arguments for the diagnostic. Defaults to {}.
+        """
+        self.append(DiagnosticInfo(type=type, location=location, args=args))
+