ZedScripts 0.0.2__tar.gz → 1.0.0__tar.gz

zedscripts-1.0.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: ZedScripts
+Version: 1.0.0
+Author: SimKDT
+License: MIT License
+        
+        Copyright (c) 2026 PZ Wiki Modding
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.12.3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lsprotocol
+Requires-Dist: pygls
+Requires-Dist: requests-cache
+Requires-Dist: pydantic
+Requires-Dist: deepmerge
+Provides-Extra: build
+Requires-Dist: pyinstaller; extra == "build"
+Provides-Extra: debug
+Requires-Dist: debugpy; extra == "debug"
+Dynamic: license-file
+
+# ZedScripts LSP
+
+[![License](https://img.shields.io/github/license/PZ-Wiki-Modding/ZedScripts?label=License)](LICENSE)
+![Code Size](https://img.shields.io/github/languages/code-size/PZ-Wiki-Modding/ZedScripts?label=Code%20Size)
+[![PyPi Version](https://img.shields.io/pypi/v/ZedScripts)](https://pypi.org/project/ZedScripts/)
+
+ZedScripts LSP is a language server protocol implemented in Python for the [scripting format](https://pzwiki.net/wiki/Scripts) of Project Zomboid. Previously a [VSCode extension](https://github.com/PZ-Wiki-Modding/ZedScripts), it is now reimplemented as a standalone LSP.
+
+It is powered by the [pz-scripts-data](https://github.com/PZ-Wiki-Modding/pz-scripts-data) to provide up-to-date information about the Scripts format. See [configuration](#configuration) to learn how to specify the dataset version.
+
+## Installation
+### Releases
+
+### Python package
+
+ZedScripts LSP is available directly as a Python package if you ever need to use its functionality outside of an IDE.
+
+<details open>
+<summary>PyPI</summary>
+
+```bash
+pip install ZedScripts
+```
+</details>
+
+<details>
+<summary>Git</summary>
+
+```bash
+pip install git+https://github.com/PZ-Wiki-Modding/ZedScripts-LSP.git
+```
+</details>
+
+<details>
+<summary>Dev</summary>
+
+```bash
+pip install -e .
+```
+</details>
+
+## Cache directory
+
+A cache directory is used on your system to cache the [pz-scripts-data](https://github.com/PZ-Wiki-Modding/pz-scripts-data) and logs, as well as global configuration. You can find it here:
+
+<details>
+<summary>Linux</summary>
+
+```bash
+~/.zedscripts
+```
+</details>
+
+<details>
+<summary>Windows</summary>
+
+```bash
+%USERPROFILE%\.zedscripts
+```
+</details>
+
+## Configuration
+
+The LSP uses configurations files `.zedscripts.json` which provide information to the LSP about various settings.
+
+Example of configuration file content:
+```json
+{
+    "$schema": "https://raw.githubusercontent.com/PZ-Wiki-Modding/ZedScripts-LSP/refs/heads/main/schema/zedscripts.json",
+    "dataset": {
+        "latest": true
+    },
+    "libraries": [
+        "~/.steam/debian-installation/steamapps/common/ProjectZomboid/projectzomboid/media",
+    ]
+}
+```
+
+They are optional and should be placed at the root of your workspaces or in the [cache directory](#cache-directory). The local configuration (root of your workspaces) will override the global configuration (cache directory).
+
+```bash
+📁 workspace1
+    📁 Contents/mods/YourMod/42/media/scripts
+        📄 example_script.txt
+    📄 .zedscripts.json
+📁 workspace2
+    📄 .zedscripts.json
+```
+```bash
+📁 ~
+    📁 .zedscripts
+        📄 .zedscripts.json
+```
+
+A schema is available to validate the configuration files and can be found in the [schema directory](schema/zedscripts.json).
+
+See the following sections for detailed explanation of each parameters.
+
+### Dataset
+You can configure the version of the [pz-scripts-data](https://github.com/PZ-Wiki-Modding/pz-scripts-data) dataset.
+
+```json
+{
+    "dataset": {
+        ...
+    }
+}
+```
+
+The key-values which can be set in the `dataset` section are the following:
+- `latest`: a boolean indicating the LSP to use the latest available version for the dataset (latest game version and dataset version)
+- `stable`: a boolean indicating the LSP to use the latest stable version of the dataset
+- `release`: used to indicate a specific release version of the dataset with the following arguments:
+  - `major`: major build version (e.g. `42`, `43`)
+  - `minor`: minor build version (e.g. `0`, `1`)
+  - `patch`: patch build version (e.g. `0`, `1`)
+  - `version` (optional): the dataset version (e.g. `0`, `1`, `2`)
+  - for example, version `42.21.0` of the game would be specified as:
+```json
+{
+    "release": {
+        "major": 42,
+        "minor": 21,
+        "patch": 0
+    }
+}
+```
+
+It's suggested to use the `stable` option.
+
+### Libraries
+A list of paths that should include the base game path, as well as other games that your mod depends on for its scripts. This will provide LSP the ability to find other blocks definitions that you may reference inside your mod's scripts.
+```json
+{
+    "libraries": [
+        "path/to/base/game",
+        "path/to/other/dependent/game"
+    ]
+}
+```
+
+### Ignored
+A list of regex patterns tested on file paths that should be ignored by the LSP, by default this includes large script files that can slow down the LSP.
+```json
+{
+    "ignored": [
+        "path/to/large/script/file"
+    ]
+}
+```
+
+### Diagnostics
+A list of diagnostics with modifiers to change the diagnostic behavior of the LSP. The following parameters:
+- `type`: the type of the diagnostic, that is the ID shown in the diagnostics hover tooltip (for example, `BLOCK_UNKNOWN_BLOCK`)
+- `enable` (optional): boolean to disable the diagnostic
+- `severity` (optional): the severity level of the diagnostic (accepted values: `Error`, `Warning`, `Information`, `Hint`)
+- `tags` (optional): an array of tags which an IDE may use to provide additional context or behavior for the diagnostic (accepted values: `Unnecessary`, `Deprecated`)
+
+Each diagnostic by default have a specific set of modifiers that can be overridden in the configuration.
+
+```json
+{
+    "diagnostics": [
+        {
+            "type": "BLOCK_UNKNOWN_BLOCK",
+            "enable": true,
+            "severity": "Warning",
+            "tags": ["Unnecessary"]
+        }
+    ]
+}
+```
+
+## IDE configuration
+Based on the IDE you use, you may need to install the ZedScripts LSP application for your OS in the [releases](https://github.com/PZ-Wiki-Modding/ZedScripts-LSP/releases) (Linux, Windows).
+
+### Visual Studio Code
+
+Install the [ZedScripts extension](https://marketplace.visualstudio.com/items?itemName=SimKDT.ZedScripts) from the Visual Studio Code marketplace. The extension will handle the downloading and setup of the ZedScripts LSP server for you.
+
+### VIM
+
+Using [yegappan/lsp](https://github.com/yegappan/lsp), setup the ZedScripts LSP server as follows:
+
+```vim
+let lspServers = [
+      \ #{
+      \   name: 'zedscripts',
+      \   filetype: ['text', 'zedscripts'],
+      \   path: 'path/to/ZedScripts',
+      \   args: []
+      \ }
+      \ ]
+
+autocmd User LspSetup call LspAddServer(lspServers)
+```
+
+> [!NOTE]
+> You can see [this video](https://www.youtube.com/watch?v=-5lb_jLQmKc) which explains how to set up VIM, and notably setup a LSP server.
+
+## License and contribution
+This project is licensed under a [MIT license](LICENSE). Before contributing to the project, please see [CONTRIBUTING](CONTRIBUTING.md).

zedscripts-1.0.0/README.md

@@ -0,0 +1,202 @@
+# ZedScripts LSP
+
+[![License](https://img.shields.io/github/license/PZ-Wiki-Modding/ZedScripts?label=License)](LICENSE)
+![Code Size](https://img.shields.io/github/languages/code-size/PZ-Wiki-Modding/ZedScripts?label=Code%20Size)
+[![PyPi Version](https://img.shields.io/pypi/v/ZedScripts)](https://pypi.org/project/ZedScripts/)
+
+ZedScripts LSP is a language server protocol implemented in Python for the [scripting format](https://pzwiki.net/wiki/Scripts) of Project Zomboid. Previously a [VSCode extension](https://github.com/PZ-Wiki-Modding/ZedScripts), it is now reimplemented as a standalone LSP.
+
+It is powered by the [pz-scripts-data](https://github.com/PZ-Wiki-Modding/pz-scripts-data) to provide up-to-date information about the Scripts format. See [configuration](#configuration) to learn how to specify the dataset version.
+
+## Installation
+### Releases
+
+### Python package
+
+ZedScripts LSP is available directly as a Python package if you ever need to use its functionality outside of an IDE.
+
+<details open>
+<summary>PyPI</summary>
+
+```bash
+pip install ZedScripts
+```
+</details>
+
+<details>
+<summary>Git</summary>
+
+```bash
+pip install git+https://github.com/PZ-Wiki-Modding/ZedScripts-LSP.git
+```
+</details>
+
+<details>
+<summary>Dev</summary>
+
+```bash
+pip install -e .
+```
+</details>
+
+## Cache directory
+
+A cache directory is used on your system to cache the [pz-scripts-data](https://github.com/PZ-Wiki-Modding/pz-scripts-data) and logs, as well as global configuration. You can find it here:
+
+<details>
+<summary>Linux</summary>
+
+```bash
+~/.zedscripts
+```
+</details>
+
+<details>
+<summary>Windows</summary>
+
+```bash
+%USERPROFILE%\.zedscripts
+```
+</details>
+
+## Configuration
+
+The LSP uses configurations files `.zedscripts.json` which provide information to the LSP about various settings.
+
+Example of configuration file content:
+```json
+{
+    "$schema": "https://raw.githubusercontent.com/PZ-Wiki-Modding/ZedScripts-LSP/refs/heads/main/schema/zedscripts.json",
+    "dataset": {
+        "latest": true
+    },
+    "libraries": [
+        "~/.steam/debian-installation/steamapps/common/ProjectZomboid/projectzomboid/media",
+    ]
+}
+```
+
+They are optional and should be placed at the root of your workspaces or in the [cache directory](#cache-directory). The local configuration (root of your workspaces) will override the global configuration (cache directory).
+
+```bash
+📁 workspace1
+    📁 Contents/mods/YourMod/42/media/scripts
+        📄 example_script.txt
+    📄 .zedscripts.json
+📁 workspace2
+    📄 .zedscripts.json
+```
+```bash
+📁 ~
+    📁 .zedscripts
+        📄 .zedscripts.json
+```
+
+A schema is available to validate the configuration files and can be found in the [schema directory](schema/zedscripts.json).
+
+See the following sections for detailed explanation of each parameters.
+
+### Dataset
+You can configure the version of the [pz-scripts-data](https://github.com/PZ-Wiki-Modding/pz-scripts-data) dataset.
+
+```json
+{
+    "dataset": {
+        ...
+    }
+}
+```
+
+The key-values which can be set in the `dataset` section are the following:
+- `latest`: a boolean indicating the LSP to use the latest available version for the dataset (latest game version and dataset version)
+- `stable`: a boolean indicating the LSP to use the latest stable version of the dataset
+- `release`: used to indicate a specific release version of the dataset with the following arguments:
+  - `major`: major build version (e.g. `42`, `43`)
+  - `minor`: minor build version (e.g. `0`, `1`)
+  - `patch`: patch build version (e.g. `0`, `1`)
+  - `version` (optional): the dataset version (e.g. `0`, `1`, `2`)
+  - for example, version `42.21.0` of the game would be specified as:
+```json
+{
+    "release": {
+        "major": 42,
+        "minor": 21,
+        "patch": 0
+    }
+}
+```
+
+It's suggested to use the `stable` option.
+
+### Libraries
+A list of paths that should include the base game path, as well as other games that your mod depends on for its scripts. This will provide LSP the ability to find other blocks definitions that you may reference inside your mod's scripts.
+```json
+{
+    "libraries": [
+        "path/to/base/game",
+        "path/to/other/dependent/game"
+    ]
+}
+```
+
+### Ignored
+A list of regex patterns tested on file paths that should be ignored by the LSP, by default this includes large script files that can slow down the LSP.
+```json
+{
+    "ignored": [
+        "path/to/large/script/file"
+    ]
+}
+```
+
+### Diagnostics
+A list of diagnostics with modifiers to change the diagnostic behavior of the LSP. The following parameters:
+- `type`: the type of the diagnostic, that is the ID shown in the diagnostics hover tooltip (for example, `BLOCK_UNKNOWN_BLOCK`)
+- `enable` (optional): boolean to disable the diagnostic
+- `severity` (optional): the severity level of the diagnostic (accepted values: `Error`, `Warning`, `Information`, `Hint`)
+- `tags` (optional): an array of tags which an IDE may use to provide additional context or behavior for the diagnostic (accepted values: `Unnecessary`, `Deprecated`)
+
+Each diagnostic by default have a specific set of modifiers that can be overridden in the configuration.
+
+```json
+{
+    "diagnostics": [
+        {
+            "type": "BLOCK_UNKNOWN_BLOCK",
+            "enable": true,
+            "severity": "Warning",
+            "tags": ["Unnecessary"]
+        }
+    ]
+}
+```
+
+## IDE configuration
+Based on the IDE you use, you may need to install the ZedScripts LSP application for your OS in the [releases](https://github.com/PZ-Wiki-Modding/ZedScripts-LSP/releases) (Linux, Windows).
+
+### Visual Studio Code
+
+Install the [ZedScripts extension](https://marketplace.visualstudio.com/items?itemName=SimKDT.ZedScripts) from the Visual Studio Code marketplace. The extension will handle the downloading and setup of the ZedScripts LSP server for you.
+
+### VIM
+
+Using [yegappan/lsp](https://github.com/yegappan/lsp), setup the ZedScripts LSP server as follows:
+
+```vim
+let lspServers = [
+      \ #{
+      \   name: 'zedscripts',
+      \   filetype: ['text', 'zedscripts'],
+      \   path: 'path/to/ZedScripts',
+      \   args: []
+      \ }
+      \ ]
+
+autocmd User LspSetup call LspAddServer(lspServers)
+```
+
+> [!NOTE]
+> You can see [this video](https://www.youtube.com/watch?v=-5lb_jLQmKc) which explains how to set up VIM, and notably setup a LSP server.
+
+## License and contribution
+This project is licensed under a [MIT license](LICENSE). Before contributing to the project, please see [CONTRIBUTING](CONTRIBUTING.md).

{zedscripts-0.0.2 → zedscripts-1.0.0}/pyproject.toml

@@ -3,9 +3,8 @@ name = "ZedScripts"
 description = ""
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12.3"
-version = "0.0.2"
-license = "MIT"
-license-files = ["LICENSE"]
+version = "1.0.0"
+license = {file = "LICENSE"}
 authors = [
   { name = "SimKDT" },
 ]
@@ -34,3 +33,10 @@ build-backend = "setuptools.build_meta"
 ZedScripts = [
     "locale/*.json"
 ]
+
+# uv configs
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

zedscripts-1.0.0/src/ZedScripts/__about__.py

@@ -0,0 +1,4 @@
+__version__ = "1.0.0"
+
+if __name__ == "__main__":
+    print(__version__)

{zedscripts-0.0.2 → zedscripts-1.0.0}/src/ZedScripts/enums/Diagnostic.py

@@ -7,7 +7,7 @@ from ..enums.SyntaxErrorType import SyntaxErrorType
 from ..providers.diagnostics import DiagnosticDefinition
 
 
-class DiagnosticType(enum.Enum):
+class DiagnosticType(enum.StrEnum):
     @classmethod
     def _missing_(cls, value: Any) -> 'DiagnosticType | None':
         if isinstance(value, SyntaxErrorType):

zedscripts-1.0.0/src/ZedScripts/environment/config.py

@@ -0,0 +1,179 @@
+import logging
+import enum
+from pathlib import Path
+from typing import Annotated, Optional
+from pydantic import BaseModel, BeforeValidator, Field, WithJsonSchema
+
+from lsprotocol.types import DiagnosticSeverity, DiagnosticTag
+
+from ..scripts.version import DataVersion
+from ..enums.Diagnostic import DiagnosticType
+
+
+
+# the auto enum of DiagnosticType makes them lowercase, but we'll want to use
+# uppercase, that is the member's name
+
+def _parse_diagnostic_type_name(value: object) -> object:
+    if isinstance(value, DiagnosticType):
+        return value
+    if isinstance(value, str):
+        try:
+            return DiagnosticType[value]
+        except KeyError:
+            raise ValueError("type must be a DiagnosticType member name") from None
+    return value
+DiagnosticTypeName = Annotated[
+    DiagnosticType,
+    BeforeValidator(_parse_diagnostic_type_name),
+    WithJsonSchema({
+        "type": "string",
+        "enum": [member.name for member in DiagnosticType],
+    }),
+]
+
+def _parse_diagnostic_severity_name(value: object) -> object:
+    if isinstance(value, DiagnosticSeverity):
+        return value
+    if isinstance(value, str):
+        try:
+            return DiagnosticSeverity[value]
+        except KeyError:
+            raise ValueError("severity must be a DiagnosticSeverity member name") from None
+    return value
+DiagnosticSeverityName = Annotated[
+    DiagnosticSeverity,
+    BeforeValidator(_parse_diagnostic_severity_name),
+    WithJsonSchema({
+        "type": "string",
+        "enum": [member.name for member in DiagnosticSeverity],
+    }),
+]
+
+def _parse_diagnostic_tag_name(value: object) -> object:
+    if isinstance(value, DiagnosticTag):
+        return value
+    if isinstance(value, str):
+        try:
+            return DiagnosticTag[value]
+        except KeyError:
+            raise ValueError("tag must be a DiagnosticTag member name") from None
+    return value
+DiagnosticTagName = Annotated[
+    DiagnosticTag,
+    BeforeValidator(_parse_diagnostic_tag_name),
+    WithJsonSchema({
+        "type": "string",
+        "enum": [member.name for member in DiagnosticTag],
+    }),
+]
+
+
+
+# define the models
+
+class DatasetTag(enum.StrEnum):
+    LATEST = "latest"
+    STABLE = "stable"
+
+
+
+class ReleaseModel(BaseModel):
+    major: int = Field(
+        description="Build game version number.",
+        ge=42,
+    )
+    minor: int = Field(
+        description="Minor game version number.",
+        ge=0,
+    )
+    patch: int = Field(
+        description="Patch game version number.",
+        ge=0,
+    )
+    version: Optional[int] = Field(
+        description="Dataset version number for the provided Build release (major.minor.patch). This is incremented whenever the dataset for a specific version is updated.",
+        default=None,
+        ge=0,
+    )
+
+class DatasetModel(BaseModel):
+    release: Optional[ReleaseModel] = Field(
+        description="Provides a configuration for the dataset version to use for validation. This overrides the `latest` and `stable` fields if set.",
+        default=None,
+    )
+    latest: Optional[bool] = Field(
+        description="Indicates whether to use the latest dataset version for validation. This is ignored if `release` is set. Overrides the `stable` field if set.",
+        default=False,
+    )
+    stable: Optional[bool] = Field(
+        description="Provides a configuration for the stable dataset version to use for validation. Ignored if `release` or `latest` is set.",
+        default=True,
+    )
+
+    def to_data_version(self) -> DataVersion | DatasetTag:
+        if self.release is None:
+            if self.latest:
+                return DatasetTag.LATEST
+            if self.stable:
+                return DatasetTag.STABLE
+            logging.warning("No dataset version specified, defaulting to 'stable'.")
+            return DatasetTag.STABLE
+        from ..scripts.dataset import Manifest
+        try:
+            return Manifest.from_release_model(self.release)
+        except Exception as e:
+            logging.error(f"Failed to get data version from release model: {e}. Defaulting to 'stable'.")
+            return DatasetTag.STABLE
+
+class DiagnosticsModel(BaseModel):
+    """Represents the diagnostics configuration for the workspace environment."""
+    type: DiagnosticTypeName = Field(
+        description="Specifies the diagnostic member name to enable.",
+    )
+    enable: Optional[bool] = Field(
+        description="Indicates whether diagnostics are enabled.",
+        default=True,
+    )
+    severity: Optional[DiagnosticSeverityName] = Field(
+        description="Specifies the severity level of the diagnostics.",
+        default=None,
+    )
+    tags: Optional[list[DiagnosticTagName]] = Field(
+        description="Specifies the tags associated with the diagnostics.",
+        default=None,
+    )
+
+class ConfigurationModel(BaseModel):
+    """Represents the content of the configuration files for workspace environments."""
+    dataset: DatasetModel = Field(
+        description="Provides configuration for the dataset version to use for diagnostics.",
+        default_factory=DatasetModel,
+    )
+    libraries: set[Path] = Field(
+        description="Set of library folders to reference. Usually this should contain the base game folder.",
+        default_factory=set,
+    )
+    ignored: set[str] = Field(
+        description="Regex patterns for files and folders to ignore in the workspace.",
+        default=set([
+            r"tileGeometry\.txt",
+            r"tileDepthTextureAssignments\.txt",
+            r".+\.tiles\.txt"
+        ]),
+    )
+    diagnostics: list[DiagnosticsModel] = Field(
+        description="List of diagnostics configurations for the workspace environment.",
+        default_factory=list,
+    )
+
+    def find_diagnostic(self, type: DiagnosticType) -> DiagnosticsModel | None:
+        for diagnostic in self.diagnostics:
+            if diagnostic.type == type:
+                return diagnostic
+        return None
+
+if __name__ == "__main__":
+    import json
+    config = ConfigurationModel()
+    print(json.dumps(config.model_json_schema(), indent=4))