win: add more Edge scripts including AI & ads

This commit improves the scripts configuring Edge. It improves their
categorization, naming and adds scripts to disable Bing ads and Search
bar along with others to disable ads/data collection.

Changes:

- Add new scripts to configure Edge, such as blocking ads and AI
  features that collects data.
- Improve categorization and documentation consistency.

.github/actions/upload-artifact/action.yaml

@@ -0,0 +1,15 @@
+inputs:
+  name:
+    required: true
+  path:
+    required: true
+
+runs:
+  using: composite
+  steps:
+    -
+      name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.name }}
+        path: ${{ inputs.path }}

.github/workflows/checks.desktop-runtime-errors.yaml

@@ -70,7 +70,7 @@ jobs:
       -
         name: Upload screenshot
         if: always() # Run even if previous step fails
-        uses: actions/upload-artifact@v3
+        uses: ./.github/actions/upload-artifact
         with:
           name: screenshot-${{ matrix.os }}
           path: screenshot.png

.github/workflows/checks.quality.yaml

@@ -74,3 +74,28 @@ jobs:
       -
         name: Analyzing the code with pylint
         run: npm run lint:pylint
+
+  validate-collection-files:
+    runs-on: ${{ matrix.os }}-latest
+    strategy:
+      matrix:
+        os: [ macos, ubuntu, windows ]
+      fail-fast: false # Still interested to see results from other combinations
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Setup node
+        uses: ./.github/actions/setup-node
+      -
+        name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      -
+        name: Install dependencies
+        run: python3 -m pip install -r ./scripts/validate-collections-yaml/requirements.txt
+      -
+        name: Validate
+        run: python3 ./scripts/validate-collections-yaml

.github/workflows/tests.e2e.yaml

@@ -51,14 +51,14 @@ jobs:
       -
         name: Upload screenshots
         if: failure() # Run only if previous steps fail because screenshots will be generated only if E2E test failed
-        uses: actions/upload-artifact@v3
+        uses: ./.github/actions/upload-artifact
         with:
           name: e2e-screenshots-${{ matrix.os }}
           path: ${{ steps.artifacts.outputs.SCREENSHOTS_DIR }}
       -
         name: Upload videos
         if: always() # Run even if previous steps fail because test run video is always captured
-        uses: actions/upload-artifact@v3
+        uses: ./.github/actions/upload-artifact
         with:
           name: e2e-videos-${{ matrix.os }}
           path: ${{ steps.artifacts.outputs.VIDEOS_DIR }}

.gitignore

@@ -14,3 +14,7 @@ node_modules
 
 # macOS
 .DS_Store
+
+# Python
+__pycache__
+.venv

.vscode/extensions.json

@@ -5,8 +5,10 @@
     "wengerk.highlight-bad-chars",      // Highlights bad chars.
     "wayou.vscode-todo-highlight",      // Highlights TODO.
     "wix.vscode-import-cost",           // Shows in KB how much a require include in code.
-    // Documentation
+    // Markdown
     "davidanson.vscode-markdownlint",   // Lints markdown.
+    // YAML
+    "redhat.vscode-yaml",               // Lints YAML files, validates against schema.
     // TypeScript / JavaScript
     "dbaeumer.vscode-eslint",           // Lints JavaScript/TypeScript.
     "pmneo.tsimporter",                 // Provides better auto-complete for TypeScripts imports.

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.13.4 (2024-05-27)
+
+* Add specific empty function name compiler error | [870120b](https://github.com/undergroundwires/privacy.sexy/commit/870120bc13909a3681e0f0a2351806849476342f)
+* ci/cd: fix recent Docker build failures on macOS | [a1922c5](https://github.com/undergroundwires/privacy.sexy/commit/a1922c50c12b3b7806e9e681ace842194a178bda)
+* win: standardize registry edit + delete on revert | [cec0b4b](https://github.com/undergroundwires/privacy.sexy/commit/cec0b4b4f63c3563a0e7923ce6324a38d71a3955)
+* Fix e2e test failing on Windows | [4a7efa2](https://github.com/undergroundwires/privacy.sexy/commit/4a7efa27c8df73ef9b7960afed29f216b066cba2)
+* Add support for macOS universal binary #348, #362 | [d25c4e8](https://github.com/undergroundwires/privacy.sexy/commit/d25c4e8c812b8d012010ba38070a2931dcd28908)
+* Migrate to GitHub issue forms | [9ab3ff7](https://github.com/undergroundwires/privacy.sexy/commit/9ab3ff75b0a69ac2ba27dd02e82db9b5bd76ea0f)
+* ci/cd: fix quality checks not running on all OSes | [2390530](https://github.com/undergroundwires/privacy.sexy/commit/2390530d929fb92c266558c52376569a0ecb90c1)
+* Bump Vue to latest and fix universal selector CSS | [aae5434](https://github.com/undergroundwires/privacy.sexy/commit/aae54344511ec51d17ad0420a92cb5a064e0e7bb)
+* Centralize and optimize `ResizeObserver` usage | [2923621](https://github.com/undergroundwires/privacy.sexy/commit/292362135db0519ec1050bab80ed373aad115731)
+* win: improve app access disabling and docs #138 | [ff3d5c4](https://github.com/undergroundwires/privacy.sexy/commit/ff3d5c48419f663379f5aba8936636c22f2c5de8)
+* win: document and discourage RSA key script #363 | [f347fde](https://github.com/undergroundwires/privacy.sexy/commit/f347fde0c85f8b51b0060fdea0a2724b042aaeed)
+* win: improve printing removal /w Print Queue #279 | [150e067](https://github.com/undergroundwires/privacy.sexy/commit/150e0670392bb62348c20ec644a4ed8a6bbffe74)
+* win: discourage blocking app access #121 #339 #350 | [7794846](https://github.com/undergroundwires/privacy.sexy/commit/77948461856e6837ddfbcbbef72a1bf9fc706b4e)
+* Improve context for errors thrown by compiler | [4212c7b](https://github.com/undergroundwires/privacy.sexy/commit/4212c7b9e0b1500378a1e4e88efc2d59f39f3d29)
+* win: document disabling firewall #115 #152 #364 | [12b1f18](https://github.com/undergroundwires/privacy.sexy/commit/12b1f183f7ce966d6ce090d98aeea7ec491f8c7c)
+* win: add script to disable Recall feature | [ce4cfdd](https://github.com/undergroundwires/privacy.sexy/commit/ce4cfdd169b7da0edc3da61143c988ed5f3c976e)
+* win, mac, linux: fix typos and dead URLs #367 | [9e34e64](https://github.com/undergroundwires/privacy.sexy/commit/9e34e644493674ca709b64a47206763d5d4bd60c)
+
+[compare](https://github.com/undergroundwires/privacy.sexy/compare/0.13.3...0.13.4)
+
 ## 0.13.3 (2024-05-11)
 
 * win: organize and document network disablement | [2eed6f4](https://github.com/undergroundwires/privacy.sexy/commit/2eed6f4afb6cf85fdc1d6acb808f82405a35cafd)

README.md

@@ -122,7 +122,7 @@
 ## Get started
 
 - 🌍️ **Online**: [https://privacy.sexy](https://privacy.sexy).
-- 🖥️ **Offline**: Download directly for: [Windows](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.3/privacy.sexy-Setup-0.13.3.exe), [macOS](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.3/privacy.sexy-0.13.3.dmg), [Linux](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.3/privacy.sexy-0.13.3.AppImage). For more options, see [here](#additional-install-options).
+- 🖥️ **Offline**: Download directly for: [Windows](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.4/privacy.sexy-Setup-0.13.4.exe), [macOS](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.4/privacy.sexy-0.13.4.dmg), [Linux](https://github.com/undergroundwires/privacy.sexy/releases/download/0.13.4/privacy.sexy-0.13.4.AppImage). For more options, see [here](#additional-install-options).
 
 See also:
 
@@ -186,3 +186,7 @@ Check [architecture.md](./docs/architecture.md) for an overview of design and ho
 Security is a top priority at privacy.sexy.
 An extensive commitment to security verification ensures this priority.
 For any security concerns or vulnerabilities, please consult the [Security Policy](./SECURITY.md).
+
+## Supporters
+
+[![Supporters appreciation banner showing the supporters](https://undergroundwires.dev/img/supporters.jpg)](https://undergroundwires.dev/supporters)

docs/application.md

@@ -41,5 +41,5 @@ Application layer compiles templating syntax during parsing to create the end sc
 
 The steps to extend the templating syntax:
 
-1. Add a new parser under [SyntaxParsers](./../src/application/Parser/Script/Compiler/Expressions/SyntaxParsers) where you can look at other parsers to understand more.
+1. Add a new parser under [SyntaxParsers](./../src/application/Parser/Executable/Script/Compiler/Expressions/SyntaxParsers) where you can look at other parsers to understand more.
-2. Register your in [CompositeExpressionParser](./../src/application/Parser/Script/Compiler/Expressions/Parser/CompositeExpressionParser.ts).
+2. Register your in [CompositeExpressionParser](./../src/application/Parser/Executable/Script/Compiler/Expressions/Parser/CompositeExpressionParser.ts).

docs/collection-files.md

@@ -1,11 +1,11 @@
 # Collection files
 
 privacy.sexy is a data-driven application that reads YAML files.
-This document details the structure and syntax of the YAML files located in [`application/collections`](./../src/application/collections/), which form the backbone of the application's data model.
+This document details the structure and syntax of the YAML files located in [`application/collections`](./../src/application/collections/), which form the backbone of the application's data model. The YAML schema [`.schema.yaml`](./../src/application/collections/.schema.yaml) is provided to provide better IDE support and be used in automated validations.
 
 Related documentation:
 
-- 📖 [`collection.yaml.d.ts`](./../src/application/collections/collection.yaml.d.ts) outlines code types.
+- 📖 [`Collections README`](./../src/application/collections/README.md) includes references to code as documentation.
 - 📖 [Script Guidelines](./script-guidelines.md) provide guidance on script creation including best-practices.
 
 ## Objects
@@ -28,11 +28,20 @@ Related documentation:
 - `scripting:` ***[`ScriptingDefinition`](#scriptingdefinition)*** **(required)**
   - Sets the scripting language for all inline code used within the collection.
 
-### `Category`
+### Executables
+
+An Executable is a logical entity that can
+
+- execute once compiled,
+- include a `docs` property for documentation.
+
+It's either [Category](#category) or a [Script](#script).
+
+#### `Category`
 
 Represents a logical group of scripts and subcategories.
 
-#### `Category` syntax
+##### `Category` syntax
 
 - `category:` *`string`*  **(required)**
   - Name of the category.
@@ -43,7 +52,7 @@ Represents a logical group of scripts and subcategories.
 - `docs`: *`string`* | `[`*`string`*`, ... ]`
   - Markdown-formatted documentation related to the category.
 
-### `Script`
+#### `Script`
 
 Represents an individual tweak.
 
@@ -58,7 +67,7 @@ Types (like [functions](#function)):
 
 📖 For detailed guidelines, see [Script Guidelines](./script-guidelines.md).
 
-#### `Script` syntax
+##### `Script` syntax
 
 - `name`: *`string`* **(required)**
   - Script name.

docs/development.md

@@ -80,8 +80,10 @@ See [ci-cd.md](./ci-cd.md) for more information.
 - [**`npm run install-deps [-- <options>]`**](../scripts/npm-install.js):
   - Manages NPM dependency installation, it offers capabilities like doing a fresh install, retries on network errors, and other features.
   - For example, you can run `npm run install-deps -- --fresh` to do clean installation of dependencies.
-- [**`python ./scripts/configure_vscode.py`**](../scripts/configure_vscode.py):
+- [**`python3 ./scripts/configure_vscode.py`**](../scripts/configure_vscode.py):
   - Optimizes Visual Studio Code settings and installs essential extensions, enhancing the development environment.
+- [**`python3 ./scripts/validate-collections-yaml`**](../scripts/validate-collections-yaml/README.md):
+  - Validates the syntax and structure of collection YAML files.
 
 #### Automation scripts
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "privacy.sexy",
-  "version": "0.13.3",
+  "version": "0.13.4",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "privacy.sexy",
-      "version": "0.13.3",
+      "version": "0.13.4",
       "hasInstallScript": true,
       "dependencies": {
         "@floating-ui/vue": "^1.0.6",
@@ -34,7 +34,7 @@
         "@vue/test-utils": "^2.4.5",
         "autoprefixer": "^10.4.19",
         "cypress": "^13.7.3",
-        "electron": "^29.3.0",
+        "electron": "^31.0.2",
         "electron-builder": "^24.13.3",
         "electron-devtools-installer": "^3.2.0",
         "electron-vite": "^2.1.0",
@@ -6645,11 +6645,12 @@
       }
     },
     "node_modules/electron": {
-      "version": "29.3.0",
+      "version": "31.0.2",
-      "resolved": "https://registry.npmjs.org/electron/-/electron-29.3.0.tgz",
+      "resolved": "https://registry.npmjs.org/electron/-/electron-31.0.2.tgz",
-      "integrity": "sha512-ZxFKm0/v48GSoBuO3DdnMlCYXefEUKUHLMsKxyXY4nZGgzbBKpF/X8haZa2paNj23CLfsCKBOtfc2vsEQiOOsA==",
+      "integrity": "sha512-55efQ5yfLN+AQHcFC00AXQqtxC3iAGaxX2GQ3EDbFJ0ca9GHNOdSXkcrdBElLleiDrR2hpXNkQxN1bDn0oxe6w==",
       "dev": true,
       "hasInstallScript": true,
+      "license": "MIT",
       "dependencies": {
         "@electron/get": "^2.0.0",
         "@types/node": "^20.9.0",
@@ -22338,9 +22339,9 @@
       }
     },
     "electron": {
-      "version": "29.3.0",
+      "version": "31.0.2",
-      "resolved": "https://registry.npmjs.org/electron/-/electron-29.3.0.tgz",
+      "resolved": "https://registry.npmjs.org/electron/-/electron-31.0.2.tgz",
-      "integrity": "sha512-ZxFKm0/v48GSoBuO3DdnMlCYXefEUKUHLMsKxyXY4nZGgzbBKpF/X8haZa2paNj23CLfsCKBOtfc2vsEQiOOsA==",
+      "integrity": "sha512-55efQ5yfLN+AQHcFC00AXQqtxC3iAGaxX2GQ3EDbFJ0ca9GHNOdSXkcrdBElLleiDrR2hpXNkQxN1bDn0oxe6w==",
       "dev": true,
       "requires": {
         "@electron/get": "^2.0.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "privacy.sexy",
-  "version": "0.13.3",
+  "version": "0.13.4",
   "private": true,
   "slogan": "Privacy is sexy",
   "description": "Enforce privacy & security best-practices on Windows, macOS and Linux, because privacy is sexy.",
@@ -59,7 +59,7 @@
     "@vue/test-utils": "^2.4.5",
     "autoprefixer": "^10.4.19",
     "cypress": "^13.7.3",
-    "electron": "^29.3.0",
+    "electron": "^31.0.2",
     "electron-builder": "^24.13.3",
     "electron-devtools-installer": "^3.2.0",
     "electron-vite": "^2.1.0",

scripts/configure_vscode.py

@@ -58,6 +58,10 @@ def add_or_update_settings() -> None:
     # 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:

scripts/validate-collections-yaml/README.md

@@ -0,0 +1,51 @@
+# validate-collections-yaml
+
+This script validates YAML collection files against a predefined schema to ensure their integrity.
+
+## Prerequisites
+
+- Python 3.x installed on your system.
+
+## Running in a Virtual Environment (Recommended)
+
+Using a virtual environment isolates dependencies and prevents conflicts.
+
+1. **Create a virtual environment:**
+
+   ```bash
+   python3 -m venv ./scripts/validate-collections-yaml/.venv
+   ```
+
+2. **Activate the virtual environment:**
+
+   ```bash
+   source ./scripts/validate-collections-yaml/.venv/bin/activate
+   ```
+
+3. **Install dependencies:**
+
+   ```bash
+   python3 -m pip install -r ./scripts/validate-collections-yaml/requirements.txt
+   ```
+
+4. **Run the script:**
+
+   ```bash
+   python3 ./scripts/validate-collections-yaml
+   ```
+
+## Running Globally
+
+Running the script globally is less recommended due to potential dependency conflicts.
+
+1. **Install dependencies:**
+
+   ```bash
+   python3 -m pip install -r ./scripts/validate-collections-yaml/requirements.txt
+   ```
+
+2. **Run the script:**
+
+   ```bash
+   python3 ./scripts/validate-collections-yaml
+   ```

scripts/validate-collections-yaml/__main__.py

@@ -0,0 +1,62 @@
+"""
+Description:
+  This script validates collection YAML files against the expected schema.
+
+Usage:
+  python3 ./scripts/validate-collections-yaml
+
+Notes:
+  This script requires the `jsonschema` and `pyyaml` packages (see requirements.txt).
+"""
+# pylint: disable=missing-function-docstring
+from os import path
+import sys
+from glob import glob
+from typing import List
+from jsonschema import exceptions, validate # pylint: disable=import-error
+import yaml # pylint: disable=import-error
+
+SCHEMA_FILE_PATH = './src/application/collections/.schema.yaml'
+COLLECTIONS_GLOB_PATTERN = './src/application/collections/*.yaml'
+
+def main() -> None:
+    schema_yaml = read_file(SCHEMA_FILE_PATH)
+    schema_json = convert_yaml_to_json(schema_yaml)
+    collection_file_paths = find_collection_files(COLLECTIONS_GLOB_PATTERN)
+    print(f'Found {len(collection_file_paths)} YAML files to validate.')
+
+    total_invalid_files = 0
+    for collection_file_path in collection_file_paths:
+        file_name = path.basename(collection_file_path)
+        print(f'Validating {file_name}...')
+        collection_yaml = read_file(collection_file_path)
+        collection_json = convert_yaml_to_json(collection_yaml)
+        try:
+            validate(instance=collection_json, schema=schema_json)
+            print(f'Success: {file_name} is valid.')
+        except exceptions.ValidationError as err:
+            print(f'Error: Validation failed for {file_name}.', file=sys.stderr)
+            print(str(err), file=sys.stderr)
+            total_invalid_files += 1
+
+    if total_invalid_files > 0:
+        print(f'Validation complete with {total_invalid_files} invalid files.', file=sys.stderr)
+        sys.exit(1)
+    else:
+        print('Validation complete. All files are valid.')
+        sys.exit(0)
+
+def read_file(file_path: str) -> str:
+    with open(file_path, 'r', encoding='utf-8') as file:
+        return file.read()
+
+def find_collection_files(glob_pattern: str) -> List[str]:
+    files = glob(glob_pattern)
+    filtered_files = [f for f in files if not path.basename(f).startswith('.')]
+    return filtered_files
+
+def convert_yaml_to_json(yaml_content: str) -> dict:
+    return yaml.safe_load(yaml_content)
+
+if __name__ == '__main__':
+    main()

scripts/validate-collections-yaml/requirements.txt

@@ -0,0 +1,6 @@
+attrs==23.2.0
+jsonschema==4.22.0
+jsonschema-specifications==2023.12.1
+PyYAML==6.0.1
+referencing==0.35.1
+rpds-py==0.18.1

src/application/Common/CustomError.ts

@@ -1,4 +1,4 @@
-import { isFunction } from '@/TypeHelpers';
+import { isFunction, type ConstructorArguments } from '@/TypeHelpers';
 
 /*
   Provides a unified and resilient way to extend errors across platforms.
@@ -12,8 +12,8 @@ import { isFunction } from '@/TypeHelpers';
     > https://web.archive.org/web/20230810014143/https://github.com/Microsoft/TypeScript-wiki/blob/main/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
 */
 export abstract class CustomError extends Error {
-  constructor(message?: string, options?: ErrorOptions) {
+  constructor(...args: ConstructorArguments<typeof Error>) {
-    super(message, options);
+    super(...args);
 
     fixPrototype(this, new.target.prototype);
     ensureStackTrace(this);

src/application/Common/Enum.ts

@@ -5,13 +5,13 @@ export type EnumType = number | string;
 export type EnumVariable<T extends EnumType, TEnumValue extends EnumType>
   = { [key in T]: TEnumValue };
 
-export interface IEnumParser<TEnum> {
+export interface EnumParser<TEnum> {
   parseEnum(value: string, propertyName: string): TEnum;
 }
 
 export function createEnumParser<T extends EnumType, TEnumValue extends EnumType>(
   enumVariable: EnumVariable<T, TEnumValue>,
-): IEnumParser<TEnumValue> {
+): EnumParser<TEnumValue> {
   return {
     parseEnum: (value, propertyName) => parseEnumValue(value, propertyName, enumVariable),
   };

src/application/Context/State/Code/Event/CodeChangedEvent.ts

@@ -1,4 +1,4 @@
-import type { IScript } from '@/domain/IScript';
+import type { Script } from '@/domain/Executables/Script/Script';
 import type { ICodePosition } from '@/application/Context/State/Code/Position/ICodePosition';
 import type { SelectedScript } from '@/application/Context/State/Selection/Script/SelectedScript';
 import type { ICodeChangedEvent } from './ICodeChangedEvent';
@@ -6,13 +6,13 @@ import type { ICodeChangedEvent } from './ICodeChangedEvent';
 export class CodeChangedEvent implements ICodeChangedEvent {
   public readonly code: string;
 
-  public readonly addedScripts: ReadonlyArray<IScript>;
+  public readonly addedScripts: ReadonlyArray<Script>;
 
-  public readonly removedScripts: ReadonlyArray<IScript>;
+  public readonly removedScripts: ReadonlyArray<Script>;
 
-  public readonly changedScripts: ReadonlyArray<IScript>;
+  public readonly changedScripts: ReadonlyArray<Script>;
 
-  private readonly scripts: Map<IScript, ICodePosition>;
+  private readonly scripts: Map<Script, ICodePosition>;
 
   constructor(
     code: string,
@@ -25,7 +25,7 @@ export class CodeChangedEvent implements ICodeChangedEvent {
     this.addedScripts = selectIfNotExists(newScripts, oldScripts);
     this.removedScripts = selectIfNotExists(oldScripts, newScripts);
     this.changedScripts = getChangedScripts(oldScripts, newScripts);
-    this.scripts = new Map<IScript, ICodePosition>();
+    this.scripts = new Map<Script, ICodePosition>();
     scripts.forEach((position, selection) => {
       this.scripts.set(selection.script, position);
     });
@@ -35,7 +35,7 @@ export class CodeChangedEvent implements ICodeChangedEvent {
     return this.scripts.size === 0;
   }
 
-  public getScriptPositionInCode(script: IScript): ICodePosition {
+  public getScriptPositionInCode(script: Script): ICodePosition {
     return this.getPositionById(script.id);
   }
 
@@ -65,7 +65,7 @@ function ensureAllPositionsExist(script: string, positions: ReadonlyArray<ICodeP
 function getChangedScripts(
   oldScripts: ReadonlyArray<SelectedScript>,
   newScripts: ReadonlyArray<SelectedScript>,
-): ReadonlyArray<IScript> {
+): ReadonlyArray<Script> {
   return newScripts
     .filter((newScript) => oldScripts.find((oldScript) => oldScript.id === newScript.id
       && oldScript.revert !== newScript.revert))

src/application/Context/State/Code/Event/ICodeChangedEvent.ts

@@ -1,11 +1,11 @@
-import type { IScript } from '@/domain/IScript';
+import type { Script } from '@/domain/Executables/Script/Script';
 import type { ICodePosition } from '@/application/Context/State/Code/Position/ICodePosition';
 
 export interface ICodeChangedEvent {
   readonly code: string;
-  readonly addedScripts: ReadonlyArray<IScript>;
+  readonly addedScripts: ReadonlyArray<Script>;
-  readonly removedScripts: ReadonlyArray<IScript>;
+  readonly removedScripts: ReadonlyArray<Script>;
-  readonly changedScripts: ReadonlyArray<IScript>;
+  readonly changedScripts: ReadonlyArray<Script>;
   isEmpty(): boolean;
-  getScriptPositionInCode(script: IScript): ICodePosition;
+  getScriptPositionInCode(script: Script): ICodePosition;
 }

src/application/Context/State/Filter/Result/AppliedFilterResult.ts

@@ -1,11 +1,11 @@
-import type { IScript } from '@/domain/IScript';
+import type { Script } from '@/domain/Executables/Script/Script';
-import type { ICategory } from '@/domain/ICategory';
+import type { Category } from '@/domain/Executables/Category/Category';
 import type { FilterResult } from './FilterResult';
 
 export class AppliedFilterResult implements FilterResult {
   constructor(
-    public readonly scriptMatches: ReadonlyArray<IScript>,
+    public readonly scriptMatches: ReadonlyArray<Script>,
-    public readonly categoryMatches: ReadonlyArray<ICategory>,
+    public readonly categoryMatches: ReadonlyArray<Category>,
     public readonly query: string,
   ) {
     if (!query) { throw new Error('Query is empty or undefined'); }

src/application/Context/State/Filter/Result/FilterResult.ts

@@ -1,8 +1,9 @@
-import type { IScript, ICategory } from '@/domain/ICategory';
+import type { Category } from '@/domain/Executables/Category/Category';
+import type { Script } from '@/domain/Executables/Script/Script';
 
 export interface FilterResult {
-  readonly categoryMatches: ReadonlyArray<ICategory>;
+  readonly categoryMatches: ReadonlyArray<Category>;
-  readonly scriptMatches: ReadonlyArray<IScript>;
+  readonly scriptMatches: ReadonlyArray<Script>;
   readonly query: string;
   hasAnyMatches(): boolean;
 }

src/application/Context/State/Filter/Strategy/LinearFilterStrategy.ts

@@ -1,7 +1,8 @@
-import type { ICategory, IScript } from '@/domain/ICategory';
+import type { Category } from '@/domain/Executables/Category/Category';
-import type { IScriptCode } from '@/domain/IScriptCode';
+import type { ScriptCode } from '@/domain/Executables/Script/Code/ScriptCode';
-import type { IDocumentable } from '@/domain/IDocumentable';
+import type { Documentable } from '@/domain/Executables/Documentable';
 import type { ICategoryCollection } from '@/domain/ICategoryCollection';
+import type { Script } from '@/domain/Executables/Script/Script';
 import { AppliedFilterResult } from '../Result/AppliedFilterResult';
 import type { FilterStrategy } from './FilterStrategy';
 import type { FilterResult } from '../Result/FilterResult';
@@ -24,7 +25,7 @@ export class LinearFilterStrategy implements FilterStrategy {
 }
 
 function matchesCategory(
-  category: ICategory,
+  category: Category,
   filterLowercase: string,
 ): boolean {
   return matchesAny(
@@ -34,7 +35,7 @@ function matchesCategory(
 }
 
 function matchesScript(
-  script: IScript,
+  script: Script,
   filterLowercase: string,
 ): boolean {
   return matchesAny(
@@ -58,7 +59,7 @@ function matchName(
 }
 
 function matchCode(
-  code: IScriptCode,
+  code: ScriptCode,
   filterLowercase: string,
 ): boolean {
   if (code.execute.toLowerCase().includes(filterLowercase)) {
@@ -71,7 +72,7 @@ function matchCode(
 }
 
 function matchDocumentation(
-  documentable: IDocumentable,
+  documentable: Documentable,
   filterLowercase: string,
 ): boolean {
   return documentable.docs.some(

src/application/Context/State/Selection/Category/CategorySelection.ts

@@ -1,9 +1,9 @@
-import type { ICategory } from '@/domain/ICategory';
+import type { Category } from '@/domain/Executables/Category/Category';
 import type { CategorySelectionChangeCommand } from './CategorySelectionChange';
 
 export interface ReadonlyCategorySelection {
-  areAllScriptsSelected(category: ICategory): boolean;
+  areAllScriptsSelected(category: Category): boolean;
-  isAnyScriptSelected(category: ICategory): boolean;
+  isAnyScriptSelected(category: Category): boolean;
 }
 
 export interface CategorySelection extends ReadonlyCategorySelection {

src/application/Context/State/Selection/Category/ScriptToCategorySelectionMapper.ts

@@ -1,4 +1,4 @@
-import type { ICategory } from '@/domain/ICategory';
+import type { Category } from '@/domain/Executables/Category/Category';
 import type { ICategoryCollection } from '@/domain/ICategoryCollection';
 import type { CategorySelectionChange, CategorySelectionChangeCommand } from './CategorySelectionChange';
 import type { CategorySelection } from './CategorySelection';
@@ -13,7 +13,7 @@ export class ScriptToCategorySelectionMapper implements CategorySelection {
 
   }
 
-  public areAllScriptsSelected(category: ICategory): boolean {
+  public areAllScriptsSelected(category: Category): boolean {
     const { selectedScripts } = this.scriptSelection;
     if (selectedScripts.length === 0) {
       return false;
@@ -27,7 +27,7 @@ export class ScriptToCategorySelectionMapper implements CategorySelection {
     );
   }
 
-  public isAnyScriptSelected(category: ICategory): boolean {
+  public isAnyScriptSelected(category: Category): boolean {
     const { selectedScripts } = this.scriptSelection;
     if (selectedScripts.length === 0) {
       return false;

src/application/Context/State/Selection/Script/DebouncedScriptSelection.ts

@@ -1,5 +1,5 @@
 import { InMemoryRepository } from '@/infrastructure/Repository/InMemoryRepository';
-import type { IScript } from '@/domain/IScript';
+import type { Script } from '@/domain/Executables/Script/Script';
 import { EventSource } from '@/infrastructure/Events/EventSource';
 import type { ReadonlyRepository, Repository } from '@/application/Repository/Repository';
 import type { ICategoryCollection } from '@/domain/ICategoryCollection';
@@ -80,7 +80,7 @@ export class DebouncedScriptSelection implements ScriptSelection {
     });
   }
 
-  public selectOnly(scripts: readonly IScript[]): void {
+  public selectOnly(scripts: readonly Script[]): void {
     assertNonEmptyScriptSelection(scripts);
     this.processChanges({
       changes: [
@@ -145,7 +145,7 @@ export class DebouncedScriptSelection implements ScriptSelection {
   }
 }
 
-function assertNonEmptyScriptSelection(selectedItems: readonly IScript[]) {
+function assertNonEmptyScriptSelection(selectedItems: readonly Script[]) {
   if (selectedItems.length === 0) {
     throw new Error('Provided script array is empty. To deselect all scripts, please use the deselectAll() method instead.');
   }
@@ -153,7 +153,7 @@ function assertNonEmptyScriptSelection(selectedItems: readonly IScript[]) {
 
 function getScriptIdsToBeSelected(
   existingItems: ReadonlyRepository<string, SelectedScript>,
-  desiredScripts: readonly IScript[],
+  desiredScripts: readonly Script[],
 ): string[] {
   return desiredScripts
     .filter((script) => !existingItems.exists(script.id))
@@ -162,7 +162,7 @@ function getScriptIdsToBeSelected(
 
 function getScriptIdsToBeDeselected(
   existingItems: ReadonlyRepository<string, SelectedScript>,
-  desiredScripts: readonly IScript[],
+  desiredScripts: readonly Script[],
 ): string[] {
   return existingItems
     .getItems()

src/application/Context/State/Selection/Script/ScriptSelection.ts

@@ -1,5 +1,5 @@
 import type { IEventSource } from '@/infrastructure/Events/IEventSource';
-import type { IScript } from '@/domain/IScript';
+import type { Script } from '@/domain/Executables/Script/Script';
 import type { SelectedScript } from './SelectedScript';
 import type { ScriptSelectionChangeCommand } from './ScriptSelectionChange';
 
@@ -10,7 +10,7 @@ export interface ReadonlyScriptSelection {
 }
 
 export interface ScriptSelection extends ReadonlyScriptSelection {
-  selectOnly(scripts: readonly IScript[]): void;
+  selectOnly(scripts: readonly Script[]): void;
   selectAll(): void;
   deselectAll(): void;
   processChanges(action: ScriptSelectionChangeCommand): void;

src/application/Context/State/Selection/Script/SelectedScript.ts

@@ -1,9 +1,9 @@
 import type { IEntity } from '@/infrastructure/Entity/IEntity';
-import type { IScript } from '@/domain/IScript';
+import type { Script } from '@/domain/Executables/Script/Script';
 
-type ScriptId = IScript['id'];
+type ScriptId = Script['id'];
 
 export interface SelectedScript extends IEntity<ScriptId> {
-  readonly script: IScript;
+  readonly script: Script;
   readonly revert: boolean;
 }

src/application/Context/State/Selection/Script/UserSelectedScript.ts

@@ -1,12 +1,12 @@
 import { BaseEntity } from '@/infrastructure/Entity/BaseEntity';
-import type { IScript } from '@/domain/IScript';
+import type { Script } from '@/domain/Executables/Script/Script';
 import type { SelectedScript } from './SelectedScript';
 
 type SelectedScriptId = SelectedScript['id'];
 
 export class UserSelectedScript extends BaseEntity<SelectedScriptId> {
   constructor(
-    public readonly script: IScript,
+    public readonly script: Script,
     public readonly revert: boolean,
   ) {
     super(script.id);

src/application/Parser/ApplicationParser.ts

@@ -1,40 +1,48 @@
 import type { CollectionData } from '@/application/collections/';
 import type { IApplication } from '@/domain/IApplication';
-import type { ProjectDetails } from '@/domain/Project/ProjectDetails';
-import type { ICategoryCollection } from '@/domain/ICategoryCollection';
 import WindowsData from '@/application/collections/windows.yaml';
 import MacOsData from '@/application/collections/macos.yaml';
 import LinuxData from '@/application/collections/linux.yaml';
-import { parseProjectDetails } from '@/application/Parser/ProjectDetailsParser';
+import { parseProjectDetails, type ProjectDetailsParser } from '@/application/Parser/ProjectDetailsParser';
 import { Application } from '@/domain/Application';
-import type { IAppMetadata } from '@/infrastructure/EnvironmentVariables/IAppMetadata';
+import { parseCategoryCollection, type CategoryCollectionParser } from './CategoryCollectionParser';
-import { EnvironmentVariablesFactory } from '@/infrastructure/EnvironmentVariables/EnvironmentVariablesFactory';
+import { createTypeValidator, type TypeValidator } from './Common/TypeValidator';
-import { parseCategoryCollection } from './CategoryCollectionParser';
 
 export function parseApplication(
-  categoryParser = parseCategoryCollection,
+  collectionsData: readonly CollectionData[] = PreParsedCollections,
-  projectDetailsParser = parseProjectDetails,
+  utilities: ApplicationParserUtilities = DefaultUtilities,
-  metadata: IAppMetadata = EnvironmentVariablesFactory.Current.instance,
-  collectionsData = PreParsedCollections,
 ): IApplication {
-  validateCollectionsData(collectionsData);
+  validateCollectionsData(collectionsData, utilities.validator);
-  const projectDetails = projectDetailsParser(metadata);
+  const projectDetails = utilities.parseProjectDetails();
   const collections = collectionsData.map(
-    (collection) => categoryParser(collection, projectDetails),
+    (collection) => utilities.parseCategoryCollection(collection, projectDetails),
   );
   const app = new Application(projectDetails, collections);
   return app;
 }
 
-export type CategoryCollectionParserType
+const PreParsedCollections: readonly CollectionData[] = [
-    = (file: CollectionData, projectDetails: ProjectDetails) => ICategoryCollection;
-
-const PreParsedCollections: readonly CollectionData [] = [
   WindowsData, MacOsData, LinuxData,
 ];
 
-function validateCollectionsData(collections: readonly CollectionData[]) {
+function validateCollectionsData(
-  if (!collections.length) {
+  collections: readonly CollectionData[],
-    throw new Error('missing collections');
+  validator: TypeValidator,
-  }
+) {
+  validator.assertNonEmptyCollection({
+    value: collections,
+    valueName: 'collections',
+  });
 }
+
+interface ApplicationParserUtilities {
+  readonly parseCategoryCollection: CategoryCollectionParser;
+  readonly validator: TypeValidator;
+  readonly parseProjectDetails: ProjectDetailsParser;
+}
+
+const DefaultUtilities: ApplicationParserUtilities = {
+  parseCategoryCollection,
+  parseProjectDetails,
+  validator: createTypeValidator(),
+};

src/application/Parser/CategoryCollectionParser.ts

@@ -3,32 +3,73 @@ import { OperatingSystem } from '@/domain/OperatingSystem';
 import type { ICategoryCollection } from '@/domain/ICategoryCollection';
 import { CategoryCollection } from '@/domain/CategoryCollection';
 import type { ProjectDetails } from '@/domain/Project/ProjectDetails';
-import { createEnumParser } from '../Common/Enum';
+import { createEnumParser, type EnumParser } from '../Common/Enum';
-import { parseCategory } from './CategoryParser';
+import { parseCategory, type CategoryParser } from './Executable/CategoryParser';
-import { CategoryCollectionParseContext } from './Script/CategoryCollectionParseContext';
+import { parseScriptingDefinition, type ScriptingDefinitionParser } from './ScriptingDefinition/ScriptingDefinitionParser';
-import { ScriptingDefinitionParser } from './ScriptingDefinition/ScriptingDefinitionParser';
+import { createTypeValidator, type TypeValidator } from './Common/TypeValidator';
+import { createCollectionUtilities, type CategoryCollectionSpecificUtilitiesFactory } from './Executable/CategoryCollectionSpecificUtilities';
 
-export function parseCategoryCollection(
+export const parseCategoryCollection: CategoryCollectionParser = (
-  content: CollectionData,
+  content,
-  projectDetails: ProjectDetails,
+  projectDetails,
-  osParser = createEnumParser(OperatingSystem),
+  utilities: CategoryCollectionParserUtilities = DefaultUtilities,
-): ICategoryCollection {
+) => {
-  validate(content);
+  validateCollection(content, utilities.validator);
-  const scripting = new ScriptingDefinitionParser()
+  const scripting = utilities.parseScriptingDefinition(content.scripting, projectDetails);
-    .parse(content.scripting, projectDetails);
+  const collectionUtilities = utilities.createUtilities(content.functions, scripting);
-  const context = new CategoryCollectionParseContext(content.functions, scripting);
+  const categories = content.actions.map(
-  const categories = content.actions.map((action) => parseCategory(action, context));
+    (action) => utilities.parseCategory(action, collectionUtilities),
-  const os = osParser.parseEnum(content.os, 'os');
-  const collection = new CategoryCollection(
-    os,
-    categories,
-    scripting,
   );
+  const os = utilities.osParser.parseEnum(content.os, 'os');
+  const collection = utilities.createCategoryCollection({
+    os, actions: categories, scripting,
+  });
   return collection;
+};
+
+export type CategoryCollectionFactory = (
+  ...parameters: ConstructorParameters<typeof CategoryCollection>
+) => ICategoryCollection;
+
+export interface CategoryCollectionParser {
+  (
+    content: CollectionData,
+    projectDetails: ProjectDetails,
+    utilities?: CategoryCollectionParserUtilities,
+  ): ICategoryCollection;
 }
 
-function validate(content: CollectionData): void {
+function validateCollection(
-  if (!content.actions.length) {
+  content: CollectionData,
-    throw new Error('content does not define any action');
+  validator: TypeValidator,
-  }
+): void {
+  validator.assertObject({
+    value: content,
+    valueName: 'collection',
+    allowedProperties: [
+      'os', 'scripting', 'actions', 'functions',
+    ],
+  });
+  validator.assertNonEmptyCollection({
+    value: content.actions,
+    valueName: '"actions" in collection',
+  });
 }
+
+interface CategoryCollectionParserUtilities {
+  readonly osParser: EnumParser<OperatingSystem>;
+  readonly validator: TypeValidator;
+  readonly parseScriptingDefinition: ScriptingDefinitionParser;
+  readonly createUtilities: CategoryCollectionSpecificUtilitiesFactory;
+  readonly parseCategory: CategoryParser;
+  readonly createCategoryCollection: CategoryCollectionFactory;
+}
+
+const DefaultUtilities: CategoryCollectionParserUtilities = {
+  osParser: createEnumParser(OperatingSystem),
+  validator: createTypeValidator(),
+  parseScriptingDefinition,
+  createUtilities: createCollectionUtilities,
+  parseCategory,
+  createCategoryCollection: (...args) => new CategoryCollection(...args),
+};

src/application/Parser/CategoryParser.ts

@@ -1,133 +0,0 @@
-import type {
-  CategoryData, ScriptData, CategoryOrScriptData,
-} from '@/application/collections/';
-import { Script } from '@/domain/Script';
-import { Category } from '@/domain/Category';
-import { NodeValidator } from '@/application/Parser/NodeValidation/NodeValidator';
-import { NodeType } from '@/application/Parser/NodeValidation/NodeType';
-import { parseDocs } from './DocumentationParser';
-import { parseScript } from './Script/ScriptParser';
-import type { ICategoryCollectionParseContext } from './Script/ICategoryCollectionParseContext';
-
-let categoryIdCounter = 0;
-
-export function parseCategory(
-  category: CategoryData,
-  context: ICategoryCollectionParseContext,
-  factory: CategoryFactoryType = CategoryFactory,
-): Category {
-  return parseCategoryRecursively({
-    categoryData: category,
-    context,
-    factory,
-  });
-}
-
-interface ICategoryParseContext {
-  readonly categoryData: CategoryData,
-  readonly context: ICategoryCollectionParseContext,
-  readonly factory: CategoryFactoryType,
-  readonly parentCategory?: CategoryData,
-}
-
-function parseCategoryRecursively(context: ICategoryParseContext): Category | never {
-  ensureValidCategory(context.categoryData, context.parentCategory);
-  const children: ICategoryChildren = {
-    subCategories: new Array<Category>(),
-    subScripts: new Array<Script>(),
-  };
-  for (const data of context.categoryData.children) {
-    parseNode({
-      nodeData: data,
-      children,
-      parent: context.categoryData,
-      factory: context.factory,
-      context: context.context,
-    });
-  }
-  try {
-    return context.factory(
-      /* id: */ categoryIdCounter++,
-      /* name: */ context.categoryData.category,
-      /* docs: */ parseDocs(context.categoryData),
-      /* categories: */ children.subCategories,
-      /* scripts: */ children.subScripts,
-    );
-  } catch (err) {
-    return new NodeValidator({
-      type: NodeType.Category,
-      selfNode: context.categoryData,
-      parentNode: context.parentCategory,
-    }).throw(err.message);
-  }
-}
-
-function ensureValidCategory(category: CategoryData, parentCategory?: CategoryData) {
-  new NodeValidator({
-    type: NodeType.Category,
-    selfNode: category,
-    parentNode: parentCategory,
-  })
-    .assertDefined(category)
-    .assertValidName(category.category)
-    .assert(
-      () => category.children.length > 0,
-      `"${category.category}" has no children.`,
-    );
-}
-
-interface ICategoryChildren {
-  subCategories: Category[];
-  subScripts: Script[];
-}
-
-interface INodeParseContext {
-  readonly nodeData: CategoryOrScriptData;
-  readonly children: ICategoryChildren;
-  readonly parent: CategoryData;
-  readonly factory: CategoryFactoryType;
-  readonly context: ICategoryCollectionParseContext;
-}
-function parseNode(context: INodeParseContext) {
-  const validator = new NodeValidator({ selfNode: context.nodeData, parentNode: context.parent });
-  validator.assertDefined(context.nodeData);
-  if (isCategory(context.nodeData)) {
-    const subCategory = parseCategoryRecursively({
-      categoryData: context.nodeData,
-      context: context.context,
-      factory: context.factory,
-      parentCategory: context.parent,
-    });
-    context.children.subCategories.push(subCategory);
-  } else if (isScript(context.nodeData)) {
-    const script = parseScript(context.nodeData, context.context);
-    context.children.subScripts.push(script);
-  } else {
-    validator.throw('Node is neither a category or a script.');
-  }
-}
-
-function isScript(data: CategoryOrScriptData): data is ScriptData {
-  return hasCode(data) || hasCall(data);
-}
-
-function isCategory(data: CategoryOrScriptData): data is CategoryData {
-  return hasProperty(data, 'category');
-}
-
-function hasCode(data: unknown): boolean {
-  return hasProperty(data, 'code');
-}
-
-function hasCall(data: unknown) {
-  return hasProperty(data, 'call');
-}
-
-function hasProperty(object: unknown, propertyName: string) {
-  return Object.prototype.hasOwnProperty.call(object, propertyName);
-}
-
-export type CategoryFactoryType = (
-  ...parameters: ConstructorParameters<typeof Category>) => Category;
-
-const CategoryFactory: CategoryFactoryType = (...parameters) => new Category(...parameters);

src/application/Parser/Common/ContextualError.ts

@@ -0,0 +1,42 @@
+import { CustomError } from '@/application/Common/CustomError';
+
+export interface ErrorWithContextWrapper {
+  (
+    error: Error,
+    additionalContext: string,
+  ): Error;
+}
+
+export const wrapErrorWithAdditionalContext: ErrorWithContextWrapper = (
+  error: Error,
+  additionalContext: string,
+) => {
+  return (error instanceof ContextualError ? error : new ContextualError(error))
+    .withAdditionalContext(additionalContext);
+};
+
+/* AggregateError is similar but isn't well-serialized or displayed by browsers */
+class ContextualError extends CustomError {
+  private readonly additionalContext = new Array<string>();
+
+  constructor(
+    public readonly innerError: Error,
+  ) {
+    super();
+  }
+
+  public withAdditionalContext(additionalContext: string): this {
+    this.additionalContext.push(additionalContext);
+    return this;
+  }
+
+  public get message(): string { // toString() is not used when Chromium logs it on console
+    return [
+      '\n',
+      this.innerError.message,
+      '\n',
+      'Additional context:',
+      ...this.additionalContext.map((context, index) => `${index + 1}: ${context}`),
+    ].join('\n');
+  }
+}

src/application/Parser/Common/TypeValidator.ts

@@ -0,0 +1,131 @@
+import type { PropertyKeys } from '@/TypeHelpers';
+import {
+  isNullOrUndefined, isArray, isPlainObject, isString,
+} from '@/TypeHelpers';
+
+export interface TypeValidator {
+  assertObject<T>(assertion: ObjectAssertion<T>): void;
+  assertNonEmptyCollection(assertion: NonEmptyCollectionAssertion): void;
+  assertNonEmptyString(assertion: NonEmptyStringAssertion): void;
+}
+
+export interface NonEmptyCollectionAssertion {
+  readonly value: unknown;
+  readonly valueName: string;
+}
+
+export interface RegexValidationRule {
+  readonly expectedMatch: RegExp;
+  readonly errorMessage: string;
+}
+
+export interface NonEmptyStringAssertion {
+  readonly value: unknown;
+  readonly valueName: string;
+  readonly rule?: RegexValidationRule;
+}
+
+export interface ObjectAssertion<T> {
+  readonly value: T | unknown;
+  readonly valueName: string;
+  readonly allowedProperties?: readonly PropertyKeys<T>[];
+}
+
+export function createTypeValidator(): TypeValidator {
+  return {
+    assertObject: (assertion) => {
+      assertDefined(assertion.value, assertion.valueName);
+      assertPlainObject(assertion.value, assertion.valueName);
+      assertNoEmptyProperties(assertion.value, assertion.valueName);
+      if (assertion.allowedProperties !== undefined) {
+        const allowedProperties = assertion.allowedProperties.map((p) => p as string);
+        assertAllowedProperties(assertion.value, assertion.valueName, allowedProperties);
+      }
+    },
+    assertNonEmptyCollection: (assertion) => {
+      assertDefined(assertion.value, assertion.valueName);
+      assertArray(assertion.value, assertion.valueName);
+      assertNonEmpty(assertion.value, assertion.valueName);
+    },
+    assertNonEmptyString: (assertion) => {
+      assertDefined(assertion.value, assertion.valueName);
+      assertString(assertion.value, assertion.valueName);
+      if (assertion.value.length === 0) {
+        throw new Error(`'${assertion.valueName}' is missing.`);
+      }
+      if (assertion.rule) {
+        if (!assertion.value.match(assertion.rule.expectedMatch)) {
+          throw new Error(assertion.rule.errorMessage);
+        }
+      }
+    },
+  };
+}
+
+function assertDefined<T>(
+  value: T,
+  valueName: string,
+): asserts value is NonNullable<T> {
+  if (isNullOrUndefined(value)) {
+    throw new Error(`'${valueName}' is missing.`);
+  }
+}
+
+function assertPlainObject(
+  value: unknown,
+  valueName: string,
+): asserts value is object {
+  if (!isPlainObject(value)) {
+    throw new Error(`'${valueName}' is not an object.`);
+  }
+}
+
+function assertNoEmptyProperties(
+  value: object,
+  valueName: string,
+): void {
+  if (Object.keys(value).length === 0) {
+    throw new Error(`'${valueName}' is an empty object without properties.`);
+  }
+}
+
+function assertAllowedProperties(
+  value: object,
+  valueName: string,
+  allowedProperties: readonly string[],
+): void {
+  const properties = Object.keys(value).map((p) => p as string);
+  const disallowedProperties = properties.filter(
+    (prop) => !allowedProperties.map((p) => p as string).includes(prop),
+  );
+  if (disallowedProperties.length > 0) {
+    throw new Error(`'${valueName}' has disallowed properties: ${disallowedProperties.join(', ')}.`);
+  }
+}
+
+function assertArray(
+  value: unknown,
+  valueName: string,
+): asserts value is Array<unknown> {
+  if (!isArray(value)) {
+    throw new Error(`'${valueName}' should be of type 'array', but is of type '${typeof value}'.`);
+  }
+}
+
+function assertString(
+  value: unknown,
+  valueName: string,
+): asserts value is string {
+  if (!isString(value)) {
+    throw new Error(`'${valueName}' should be of type 'string', but is of type '${typeof value}'.`);
+  }
+}
+
+function assertNonEmpty(
+  value: Array<unknown>,
+  valueName: string,
+): void {
+  if (value.length === 0) {
+    throw new Error(`'${valueName}' cannot be an empty array.`);
+  }
+}

src/application/Parser/Executable/CategoryCollectionSpecificUtilities.ts

@@ -0,0 +1,35 @@
+import type { IScriptingDefinition } from '@/domain/IScriptingDefinition';
+import type { FunctionData } from '@/application/collections/';
+import { ScriptCompiler } from './Script/Compiler/ScriptCompiler';
+import { SyntaxFactory } from './Script/Validation/Syntax/SyntaxFactory';
+import type { IScriptCompiler } from './Script/Compiler/IScriptCompiler';
+import type { ILanguageSyntax } from './Script/Validation/Syntax/ILanguageSyntax';
+import type { ISyntaxFactory } from './Script/Validation/Syntax/ISyntaxFactory';
+
+export interface CategoryCollectionSpecificUtilities {
+  readonly compiler: IScriptCompiler;
+  readonly syntax: ILanguageSyntax;
+}
+
+export const createCollectionUtilities: CategoryCollectionSpecificUtilitiesFactory = (
+  functionsData: ReadonlyArray<FunctionData> | undefined,
+  scripting: IScriptingDefinition,
+  syntaxFactory: ISyntaxFactory = new SyntaxFactory(),
+) => {
+  const syntax = syntaxFactory.create(scripting.language);
+  return {
+    compiler: new ScriptCompiler({
+      functions: functionsData ?? [],
+      syntax,
+    }),
+    syntax,
+  };
+};
+
+export interface CategoryCollectionSpecificUtilitiesFactory {
+  (
+    functionsData: ReadonlyArray<FunctionData> | undefined,
+    scripting: IScriptingDefinition,
+    syntaxFactory?: ISyntaxFactory,
+  ): CategoryCollectionSpecificUtilities;
+}

src/application/Parser/Executable/CategoryParser.ts

@@ -0,0 +1,187 @@
+import type {
+  CategoryData, ScriptData, ExecutableData,
+} from '@/application/collections/';
+import { wrapErrorWithAdditionalContext, type ErrorWithContextWrapper } from '@/application/Parser/Common/ContextualError';
+import type { Category } from '@/domain/Executables/Category/Category';
+import { CollectionCategory } from '@/domain/Executables/Category/CollectionCategory';
+import type { Script } from '@/domain/Executables/Script/Script';
+import { parseDocs, type DocsParser } from './DocumentationParser';
+import { parseScript, type ScriptParser } from './Script/ScriptParser';
+import { createExecutableDataValidator, type ExecutableValidator, type ExecutableValidatorFactory } from './Validation/ExecutableValidator';
+import { ExecutableType } from './Validation/ExecutableType';
+import type { CategoryCollectionSpecificUtilities } from './CategoryCollectionSpecificUtilities';
+
+let categoryIdCounter = 0;
+
+export const parseCategory: CategoryParser = (
+  category: CategoryData,
+  collectionUtilities: CategoryCollectionSpecificUtilities,
+  categoryUtilities: CategoryParserUtilities = DefaultCategoryParserUtilities,
+) => {
+  return parseCategoryRecursively({
+    categoryData: category,
+    collectionUtilities,
+    categoryUtilities,
+  });
+};
+
+export interface CategoryParser {
+  (
+    category: CategoryData,
+    collectionUtilities: CategoryCollectionSpecificUtilities,
+    categoryUtilities?: CategoryParserUtilities,
+  ): Category;
+}
+
+interface CategoryParseContext {
+  readonly categoryData: CategoryData;
+  readonly collectionUtilities: CategoryCollectionSpecificUtilities;
+  readonly parentCategory?: CategoryData;
+  readonly categoryUtilities: CategoryParserUtilities;
+}
+
+function parseCategoryRecursively(
+  context: CategoryParseContext,
+): Category | never {
+  const validator = ensureValidCategory(context);
+  const children: CategoryChildren = {
+    subcategories: new Array<Category>(),
+    subscripts: new Array<Script>(),
+  };
+  for (const data of context.categoryData.children) {
+    parseUnknownExecutable({
+      data,
+      children,
+      parent: context.categoryData,
+      categoryUtilities: context.categoryUtilities,
+      collectionUtilities: context.collectionUtilities,
+    });
+  }
+  try {
+    return context.categoryUtilities.createCategory({
+      id: categoryIdCounter++,
+      name: context.categoryData.category,
+      docs: context.categoryUtilities.parseDocs(context.categoryData),
+      subcategories: children.subcategories,
+      scripts: children.subscripts,
+    });
+  } catch (error) {
+    throw context.categoryUtilities.wrapError(
+      error,
+      validator.createContextualErrorMessage('Failed to parse category.'),
+    );
+  }
+}
+
+function ensureValidCategory(
+  context: CategoryParseContext,
+): ExecutableValidator {
+  const category = context.categoryData;
+  const validator: ExecutableValidator = context.categoryUtilities.createValidator({
+    type: ExecutableType.Category,
+    self: context.categoryData,
+    parentCategory: context.parentCategory,
+  });
+  validator.assertType((v) => v.assertObject({
+    value: category,
+    valueName: category.category ?? 'category',
+    allowedProperties: [
+      'docs', 'children', 'category',
+    ],
+  }));
+  validator.assertValidName(category.category);
+  validator.assertType((v) => v.assertNonEmptyCollection({
+    value: category.children,
+    valueName: category.category,
+  }));
+  return validator;
+}
+
+interface CategoryChildren {
+  readonly subcategories: Category[];
+  readonly subscripts: Script[];
+}
+
+interface ExecutableParseContext {
+  readonly data: ExecutableData;
+  readonly children: CategoryChildren;
+  readonly parent: CategoryData;
+  readonly collectionUtilities: CategoryCollectionSpecificUtilities;
+  readonly categoryUtilities: CategoryParserUtilities;
+}
+
+function parseUnknownExecutable(context: ExecutableParseContext) {
+  const validator: ExecutableValidator = context.categoryUtilities.createValidator({
+    self: context.data,
+    parentCategory: context.parent,
+  });
+  validator.assertType((v) => v.assertObject({
+    value: context.data,
+    valueName: 'Executable',
+  }));
+  validator.assert(
+    () => isCategory(context.data) || isScript(context.data),
+    'Executable is neither a category or a script.',
+  );
+  if (isCategory(context.data)) {
+    const subCategory = parseCategoryRecursively({
+      categoryData: context.data,
+      collectionUtilities: context.collectionUtilities,
+      parentCategory: context.parent,
+      categoryUtilities: context.categoryUtilities,
+    });
+    context.children.subcategories.push(subCategory);
+  } else { // A script
+    const script = context.categoryUtilities.parseScript(context.data, context.collectionUtilities);
+    context.children.subscripts.push(script);
+  }
+}
+
+function isScript(data: ExecutableData): data is ScriptData {
+  return hasCode(data) || hasCall(data);
+}
+
+function isCategory(data: ExecutableData): data is CategoryData {
+  return hasProperty(data, 'category');
+}
+
+function hasCode(data: unknown): boolean {
+  return hasProperty(data, 'code');
+}
+
+function hasCall(data: unknown) {
+  return hasProperty(data, 'call');
+}
+
+function hasProperty(
+  object: unknown,
+  propertyName: string,
+): object is NonNullable<object> {
+  if (typeof object !== 'object') {
+    return false;
+  }
+  if (object === null) { // `typeof object` is `null`
+    return false;
+  }
+  return Object.prototype.hasOwnProperty.call(object, propertyName);
+}
+
+export type CategoryFactory = (
+  ...parameters: ConstructorParameters<typeof CollectionCategory>
+) => Category;
+
+interface CategoryParserUtilities {
+  readonly createCategory: CategoryFactory;
+  readonly wrapError: ErrorWithContextWrapper;
+  readonly createValidator: ExecutableValidatorFactory;
+  readonly parseScript: ScriptParser;
+  readonly parseDocs: DocsParser;
+}
+
+const DefaultCategoryParserUtilities: CategoryParserUtilities = {
+  createCategory: (...parameters) => new CollectionCategory(...parameters),
+  wrapError: wrapErrorWithAdditionalContext,
+  createValidator: createExecutableDataValidator,
+  parseScript,
+  parseDocs,
+};

src/application/Parser/Executable/DocumentationParser.ts

@@ -1,7 +1,7 @@
 import type { DocumentableData, DocumentationData } from '@/application/collections/';
 import { isString, isArray } from '@/TypeHelpers';
 
-export function parseDocs(documentable: DocumentableData): readonly string[] {
+export const parseDocs: DocsParser = (documentable) => {
   const { docs } = documentable;
   if (!docs) {
     return [];
@@ -9,6 +9,12 @@ export function parseDocs(documentable: DocumentableData): readonly string[] {
   let result = new DocumentationContainer();
   result = addDocs(docs, result);
   return result.getAll();
+};
+
+export interface DocsParser {
+  (
+    documentable: DocumentableData,
+  ): readonly string[];
 }
 
 function addDocs(
@@ -44,5 +50,5 @@ class DocumentationContainer {
 }
 
 function throwInvalidType(): never {
-  throw new Error('docs field (documentation) must be an array of strings');
+  throw new Error('docs field (documentation) must be a single string or an array of strings.');
 }

src/application/Parser/Executable/Script/Compiler/Expressions/Expression/Expression.ts

@@ -1,4 +1,4 @@
-import { FunctionParameterCollection } from '@/application/Parser/Script/Compiler/Function/Parameter/FunctionParameterCollection';
+import { FunctionParameterCollection } from '@/application/Parser/Executable/Script/Compiler/Function/Parameter/FunctionParameterCollection';
 import { FunctionCallArgumentCollection } from '../../Function/Call/Argument/FunctionCallArgumentCollection';
 import { ExpressionEvaluationContext, type IExpressionEvaluationContext } from './ExpressionEvaluationContext';
 import { ExpressionPosition } from './ExpressionPosition';
@@ -7,15 +7,18 @@ import type { IReadOnlyFunctionParameterCollection } from '../../Function/Parame
 import type { IExpression } from './IExpression';
 
 export type ExpressionEvaluator = (context: IExpressionEvaluationContext) => string;
+
 export class Expression implements IExpression {
   public readonly parameters: IReadOnlyFunctionParameterCollection;
 
-  constructor(
+  public readonly position: ExpressionPosition;
-    public readonly position: ExpressionPosition,
+
-    public readonly evaluator: ExpressionEvaluator,
+  public readonly evaluator: ExpressionEvaluator;
-    parameters?: IReadOnlyFunctionParameterCollection,
+
-  ) {
+  constructor(parameters: ExpressionInitParameters) {
-    this.parameters = parameters ?? new FunctionParameterCollection();
+    this.parameters = parameters.parameters ?? new FunctionParameterCollection();
+    this.evaluator = parameters.evaluator;
+    this.position = parameters.position;
   }
 
   public evaluate(context: IExpressionEvaluationContext): string {
@@ -26,6 +29,12 @@ export class Expression implements IExpression {
   }
 }
 
+export interface ExpressionInitParameters {
+  readonly position: ExpressionPosition,
+  readonly evaluator: ExpressionEvaluator,
+  readonly parameters?: IReadOnlyFunctionParameterCollection,
+}
+
 function validateThatAllRequiredParametersAreSatisfied(
   parameters: IReadOnlyFunctionParameterCollection,
   args: IReadOnlyFunctionCallArgumentCollection,

src/application/Parser/Executable/Script/Compiler/Expressions/Expression/ExpressionPositionFactory.ts

@@ -1,8 +1,13 @@
 import { ExpressionPosition } from './ExpressionPosition';
 
-export function createPositionFromRegexFullMatch(
+export interface ExpressionPositionFactory {
-  match: RegExpMatchArray,
+  (
-): ExpressionPosition {
+    match: RegExpMatchArray,
+  ): ExpressionPosition
+}
+
+export const createPositionFromRegexFullMatch
+: ExpressionPositionFactory = (match) => {
   const startPos = match.index;
   if (startPos === undefined) {
     throw new Error(`Regex match did not yield any results: ${JSON.stringify(match)}`);
@@ -13,4 +18,4 @@ export function createPositionFromRegexFullMatch(
   }
   const endPos = startPos + fullMatch.length;
   return new ExpressionPosition(startPos, endPos);
-}
+};

src/application/Parser/Executable/Script/Compiler/Expressions/ExpressionsCompiler.ts

@@ -1,4 +1,4 @@
-import { type IExpressionEvaluationContext, ExpressionEvaluationContext } from '@/application/Parser/Script/Compiler/Expressions/Expression/ExpressionEvaluationContext';
+import { type IExpressionEvaluationContext, ExpressionEvaluationContext } from '@/application/Parser/Executable/Script/Compiler/Expressions/Expression/ExpressionEvaluationContext';
 import { CompositeExpressionParser } from './Parser/CompositeExpressionParser';
 import type { IReadOnlyFunctionCallArgumentCollection } from '../Function/Call/Argument/IFunctionCallArgumentCollection';
 import type { IExpressionsCompiler } from './IExpressionsCompiler';

src/application/Parser/Executable/Script/Compiler/Expressions/Parser/CompositeExpressionParser.ts

@@ -3,10 +3,10 @@ import { WithParser } from '../SyntaxParsers/WithParser';
 import type { IExpression } from '../Expression/IExpression';
 import type { IExpressionParser } from './IExpressionParser';
 
-const Parsers = [
+const Parsers: readonly IExpressionParser[] = [
   new ParameterSubstitutionParser(),
   new WithParser(),
-];
+] as const;
 
 export class CompositeExpressionParser implements IExpressionParser {
   public constructor(private readonly leafs: readonly IExpressionParser[] = Parsers) {

src/application/Parser/Executable/Script/Compiler/Expressions/Parser/Regex/RegexParser.ts

@@ -0,0 +1,127 @@
+import { wrapErrorWithAdditionalContext, type ErrorWithContextWrapper } from '@/application/Parser/Common/ContextualError';
+import { Expression, type ExpressionEvaluator } from '../../Expression/Expression';
+import { createPositionFromRegexFullMatch, type ExpressionPositionFactory } from '../../Expression/ExpressionPositionFactory';
+import { createFunctionParameterCollection, type FunctionParameterCollectionFactory } from '../../../Function/Parameter/FunctionParameterCollectionFactory';
+import type { IExpressionParser } from '../IExpressionParser';
+import type { IExpression } from '../../Expression/IExpression';
+import type { FunctionParameter } from '../../../Function/Parameter/FunctionParameter';
+import type { IFunctionParameterCollection, IReadOnlyFunctionParameterCollection } from '../../../Function/Parameter/IFunctionParameterCollection';
+
+export interface RegexParserUtilities {
+  readonly wrapError: ErrorWithContextWrapper;
+  readonly createPosition: ExpressionPositionFactory;
+  readonly createExpression: ExpressionFactory;
+  readonly createParameterCollection: FunctionParameterCollectionFactory;
+}
+
+export abstract class RegexParser implements IExpressionParser {
+  protected abstract readonly regex: RegExp;
+
+  public constructor(
+    private readonly utilities: RegexParserUtilities = DefaultRegexParserUtilities,
+  ) {
+
+  }
+
+  public findExpressions(code: string): IExpression[] {
+    return Array.from(this.findRegexExpressions(code));
+  }
+
+  protected abstract buildExpression(match: RegExpMatchArray): PrimitiveExpression;
+
+  private* findRegexExpressions(code: string): Iterable<IExpression> {
+    if (!code) {
+      throw new Error(
+        this.buildErrorMessageWithContext({ errorMessage: 'missing code', code: 'EMPTY' }),
+      );
+    }
+    const createErrorContext = (message: string): ErrorContext => ({ code, errorMessage: message });
+    const matches = this.doOrRethrow(
+      () => code.matchAll(this.regex),
+      createErrorContext('Failed to match regex.'),
+    );
+    for (const match of matches) {
+      const primitiveExpression = this.doOrRethrow(
+        () => this.buildExpression(match),
+        createErrorContext('Failed to build expression.'),
+      );
+      const position = this.doOrRethrow(
+        () => this.utilities.createPosition(match),
+        createErrorContext('Failed to create position.'),
+      );
+      const parameters = this.doOrRethrow(
+        () => createParameters(
+          primitiveExpression,
+          this.utilities.createParameterCollection(),
+        ),
+        createErrorContext('Failed to create parameters.'),
+      );
+      const expression = this.doOrRethrow(
+        () => this.utilities.createExpression({
+          position,
+          evaluator: primitiveExpression.evaluator,
+          parameters,
+        }),
+        createErrorContext('Failed to create expression.'),
+      );
+      yield expression;
+    }
+  }
+
+  private doOrRethrow<T>(
+    action: () => T,
+    context: ErrorContext,
+  ): T {
+    try {
+      return action();
+    } catch (error) {
+      throw this.utilities.wrapError(
+        error,
+        this.buildErrorMessageWithContext(context),
+      );
+    }
+  }
+
+  private buildErrorMessageWithContext(context: ErrorContext): string {
+    return [
+      context.errorMessage,
+      `Class name: ${this.constructor.name}`,
+      `Regex pattern used: ${this.regex}`,
+      `Code: ${context.code}`,
+    ].join('\n');
+  }
+}
+
+interface ErrorContext {
+  readonly errorMessage: string,
+  readonly code: string,
+}
+
+function createParameters(
+  expression: PrimitiveExpression,
+  parameterCollection: IFunctionParameterCollection,
+): IReadOnlyFunctionParameterCollection {
+  return (expression.parameters || [])
+    .reduce((parameters, parameter) => {
+      parameters.addParameter(parameter);
+      return parameters;
+    }, parameterCollection);
+}
+
+export interface PrimitiveExpression {
+  readonly evaluator: ExpressionEvaluator;
+  readonly parameters?: readonly FunctionParameter[];
+}
+
+export interface ExpressionFactory {
+  (
+    ...args: ConstructorParameters<typeof Expression>
+  ): IExpression;
+}
+
+const DefaultRegexParserUtilities: RegexParserUtilities = {
+  wrapError: wrapErrorWithAdditionalContext,
+  createPosition: createPositionFromRegexFullMatch,
+  createExpression: (...args) => new Expression(...args),
+  createParameterCollection: createFunctionParameterCollection,
+};

src/application/Parser/Executable/Script/Compiler/Expressions/SyntaxParsers/ParameterSubstitutionParser.ts

@@ -1,5 +1,4 @@
-import { FunctionParameter } from '@/application/Parser/Script/Compiler/Function/Parameter/FunctionParameter';
+import { RegexParser, type PrimitiveExpression } from '../Parser/Regex/RegexParser';
-import { RegexParser, type IPrimitiveExpression } from '../Parser/Regex/RegexParser';
 import { ExpressionRegexBuilder } from '../Parser/Regex/ExpressionRegexBuilder';
 
 export class ParameterSubstitutionParser extends RegexParser {
@@ -12,11 +11,14 @@ export class ParameterSubstitutionParser extends RegexParser {
     .expectExpressionEnd()
     .buildRegExp();
 
-  protected buildExpression(match: RegExpMatchArray): IPrimitiveExpression {
+  protected buildExpression(match: RegExpMatchArray): PrimitiveExpression {
     const parameterName = match[1];
     const pipeline = match[2];
     return {
-      parameters: [new FunctionParameter(parameterName, false)],
+      parameters: [{
+        name: parameterName,
+        isOptional: false,
+      }],
       evaluator: (context) => {
         const { argumentValue } = context.args.getArgument(parameterName);
         if (!pipeline) {

src/application/Parser/Executable/Script/Compiler/Expressions/SyntaxParsers/WithParser.ts

@@ -1,7 +1,6 @@
 // eslint-disable-next-line max-classes-per-file
-import type { IExpressionParser } from '@/application/Parser/Script/Compiler/Expressions/Parser/IExpressionParser';
+import type { IExpressionParser } from '@/application/Parser/Executable/Script/Compiler/Expressions/Parser/IExpressionParser';
-import { FunctionParameterCollection } from '@/application/Parser/Script/Compiler/Function/Parameter/FunctionParameterCollection';
+import { FunctionParameterCollection } from '@/application/Parser/Executable/Script/Compiler/Function/Parameter/FunctionParameterCollection';
-import { FunctionParameter } from '@/application/Parser/Script/Compiler/Function/Parameter/FunctionParameter';
 import { ExpressionPosition } from '../Expression/ExpressionPosition';
 import { ExpressionRegexBuilder } from '../Parser/Regex/ExpressionRegexBuilder';
 import { createPositionFromRegexFullMatch } from '../Expression/ExpressionPositionFactory';
@@ -84,7 +83,10 @@ class WithStatementBuilder {
 
   public buildExpression(endExpressionPosition: ExpressionPosition, input: string): IExpression {
     const parameters = new FunctionParameterCollection();
-    parameters.addParameter(new FunctionParameter(this.parameterName, true));
+    parameters.addParameter({
+      name: this.parameterName,
+      isOptional: true,
+    });
     const position = new ExpressionPosition(
       this.startExpressionPosition.start,
       endExpressionPosition.end,

src/application/Parser/Executable/Script/Compiler/Function/Call/Argument/FunctionCallArgument.ts

@@ -0,0 +1,41 @@
+import { createTypeValidator, type TypeValidator } from '@/application/Parser/Common/TypeValidator';
+import { validateParameterName, type ParameterNameValidator } from '@/application/Parser/Executable/Script/Compiler/Function/Shared/ParameterNameValidator';
+
+export interface FunctionCallArgument {
+  readonly parameterName: string;
+  readonly argumentValue: string;
+}
+
+export interface FunctionCallArgumentFactory {
+  (
+    parameterName: string,
+    argumentValue: string,
+    utilities?: FunctionCallArgumentFactoryUtilities,
+  ): FunctionCallArgument;
+}
+
+export const createFunctionCallArgument: FunctionCallArgumentFactory = (
+  parameterName: string,
+  argumentValue: string,
+  utilities: FunctionCallArgumentFactoryUtilities = DefaultUtilities,
+): FunctionCallArgument => {
+  utilities.validateParameterName(parameterName);
+  utilities.typeValidator.assertNonEmptyString({
+    value: argumentValue,
+    valueName: `Missing argument value for the parameter "${parameterName}".`,
+  });
+  return {
+    parameterName,
+    argumentValue,
+  };
+};
+
+interface FunctionCallArgumentFactoryUtilities {
+  readonly typeValidator: TypeValidator;
+  readonly validateParameterName: ParameterNameValidator;
+}
+
+const DefaultUtilities: FunctionCallArgumentFactoryUtilities = {
+  typeValidator: createTypeValidator(),
+  validateParameterName,
+};

src/application/Parser/Executable/Script/Compiler/Function/Call/Argument/FunctionCallArgumentCollection.ts

@@ -1,10 +1,10 @@
-import type { IFunctionCallArgument } from './IFunctionCallArgument';
+import type { FunctionCallArgument } from './FunctionCallArgument';
 import type { IFunctionCallArgumentCollection } from './IFunctionCallArgumentCollection';
 
 export class FunctionCallArgumentCollection implements IFunctionCallArgumentCollection {
-  private readonly arguments = new Map<string, IFunctionCallArgument>();
+  private readonly arguments = new Map<string, FunctionCallArgument>();
 
-  public addArgument(argument: IFunctionCallArgument): void {
+  public addArgument(argument: FunctionCallArgument): void {
     if (this.hasArgument(argument.parameterName)) {
       throw new Error(`argument value for parameter ${argument.parameterName} is already provided`);
     }
@@ -22,7 +22,7 @@ export class FunctionCallArgumentCollection implements IFunctionCallArgumentColl
     return this.arguments.has(parameterName);
   }
 
-  public getArgument(parameterName: string): IFunctionCallArgument {
+  public getArgument(parameterName: string): FunctionCallArgument {
     if (!parameterName) {
       throw new Error('missing parameter name');
     }

src/application/Parser/Executable/Script/Compiler/Function/Call/Argument/IFunctionCallArgumentCollection.ts

@@ -1,11 +1,11 @@
-import type { IFunctionCallArgument } from './IFunctionCallArgument';
+import type { FunctionCallArgument } from './FunctionCallArgument';
 
 export interface IReadOnlyFunctionCallArgumentCollection {
-  getArgument(parameterName: string): IFunctionCallArgument;
+  getArgument(parameterName: string): FunctionCallArgument;
   getAllParameterNames(): string[];
   hasArgument(parameterName: string): boolean;
 }
 
 export interface IFunctionCallArgumentCollection extends IReadOnlyFunctionCallArgumentCollection {
-  addArgument(argument: IFunctionCallArgument): void;
+  addArgument(argument: FunctionCallArgument): void;
 }

src/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/FunctionCallCompilationContext.ts

@@ -1,4 +1,4 @@
-import type { ISharedFunctionCollection } from '@/application/Parser/Script/Compiler/Function/ISharedFunctionCollection';
+import type { ISharedFunctionCollection } from '@/application/Parser/Executable/Script/Compiler/Function/ISharedFunctionCollection';
 import type { FunctionCall } from '../FunctionCall';
 import type { SingleCallCompiler } from './SingleCall/SingleCallCompiler';
 

src/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/FunctionCallCompiler.ts

@@ -1,4 +1,4 @@
-import type { ISharedFunctionCollection } from '@/application/Parser/Script/Compiler/Function/ISharedFunctionCollection';
+import type { ISharedFunctionCollection } from '@/application/Parser/Executable/Script/Compiler/Function/ISharedFunctionCollection';
 import type { CompiledCode } from './CompiledCode';
 import type { FunctionCall } from '../FunctionCall';
 

src/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/FunctionCallSequenceCompiler.ts

@@ -1,4 +1,4 @@
-import type { FunctionCall } from '@/application/Parser/Script/Compiler/Function/Call/FunctionCall';
+import type { FunctionCall } from '@/application/Parser/Executable/Script/Compiler/Function/Call/FunctionCall';
 import { NewlineCodeSegmentMerger } from './CodeSegmentJoin/NewlineCodeSegmentMerger';
 import { AdaptiveFunctionCallCompiler } from './SingleCall/AdaptiveFunctionCallCompiler';
 import type { ISharedFunctionCollection } from '../../ISharedFunctionCollection';

src/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/SingleCall/AdaptiveFunctionCallCompiler.ts

@@ -72,7 +72,7 @@ function throwIfUnexpectedParametersExist(
     // eslint-disable-next-line prefer-template
     `Function "${functionName}" has unexpected parameter(s) provided: `
       + `"${unexpectedParameters.join('", "')}"`
-      + '. Expected parameter(s): '
+      + '.\nExpected parameter(s): '
-      + (expectedParameters.length ? `"${expectedParameters.join('", "')}"` : 'none'),
+      + (expectedParameters.length ? `"${expectedParameters.join('", "')}".` : 'none'),
   );
 }

src/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/SingleCall/SingleCallCompilerStrategy.ts

@@ -1,5 +1,5 @@
-import type { ISharedFunction } from '@/application/Parser/Script/Compiler/Function/ISharedFunction';
+import type { ISharedFunction } from '@/application/Parser/Executable/Script/Compiler/Function/ISharedFunction';
-import type { FunctionCall } from '@/application/Parser/Script/Compiler/Function/Call/FunctionCall';
+import type { FunctionCall } from '@/application/Parser/Executable/Script/Compiler/Function/Call/FunctionCall';
 import type { CompiledCode } from '../CompiledCode';
 import type { FunctionCallCompilationContext } from '../FunctionCallCompilationContext';
 

src/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/SingleCall/Strategies/Argument/ArgumentCompiler.ts

@@ -1,5 +1,5 @@
-import type { FunctionCall } from '@/application/Parser/Script/Compiler/Function/Call/FunctionCall';
+import type { FunctionCall } from '@/application/Parser/Executable/Script/Compiler/Function/Call/FunctionCall';
-import type { FunctionCallCompilationContext } from '@/application/Parser/Script/Compiler/Function/Call/Compiler/FunctionCallCompilationContext';
+import type { FunctionCallCompilationContext } from '@/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/FunctionCallCompilationContext';
 
 export interface ArgumentCompiler {
   createCompiledNestedCall(

src/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/SingleCall/Strategies/Argument/NestedFunctionArgumentCompiler.ts

@@ -1,17 +1,16 @@
-import type { IReadOnlyFunctionCallArgumentCollection } from '@/application/Parser/Script/Compiler/Function/Call/Argument/IFunctionCallArgumentCollection';
+import type { IReadOnlyFunctionCallArgumentCollection } from '@/application/Parser/Executable/Script/Compiler/Function/Call/Argument/IFunctionCallArgumentCollection';
-import { FunctionCallArgument } from '@/application/Parser/Script/Compiler/Function/Call/Argument/FunctionCallArgument';
+import { FunctionCallArgumentCollection } from '@/application/Parser/Executable/Script/Compiler/Function/Call/Argument/FunctionCallArgumentCollection';
-import { FunctionCallArgumentCollection } from '@/application/Parser/Script/Compiler/Function/Call/Argument/FunctionCallArgumentCollection';
+import { ExpressionsCompiler } from '@/application/Parser/Executable/Script/Compiler/Expressions/ExpressionsCompiler';
-import { ExpressionsCompiler } from '@/application/Parser/Script/Compiler/Expressions/ExpressionsCompiler';
+import type { IExpressionsCompiler } from '@/application/Parser/Executable/Script/Compiler/Expressions/IExpressionsCompiler';
-import type { IExpressionsCompiler } from '@/application/Parser/Script/Compiler/Expressions/IExpressionsCompiler';
+import type { FunctionCall } from '@/application/Parser/Executable/Script/Compiler/Function/Call/FunctionCall';
-import type { FunctionCall } from '@/application/Parser/Script/Compiler/Function/Call/FunctionCall';
+import type { FunctionCallCompilationContext } from '@/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/FunctionCallCompilationContext';
-import type { FunctionCallCompilationContext } from '@/application/Parser/Script/Compiler/Function/Call/Compiler/FunctionCallCompilationContext';
+import { ParsedFunctionCall } from '@/application/Parser/Executable/Script/Compiler/Function/Call/ParsedFunctionCall';
-import { ParsedFunctionCall } from '@/application/Parser/Script/Compiler/Function/Call/ParsedFunctionCall';
+import { wrapErrorWithAdditionalContext, type ErrorWithContextWrapper } from '@/application/Parser/Common/ContextualError';
+import { createFunctionCallArgument, type FunctionCallArgument, type FunctionCallArgumentFactory } from '@/application/Parser/Executable/Script/Compiler/Function/Call/Argument/FunctionCallArgument';
 import type { ArgumentCompiler } from './ArgumentCompiler';
 
 export class NestedFunctionArgumentCompiler implements ArgumentCompiler {
-  constructor(
+  constructor(private readonly utilities: ArgumentCompilationUtilities = DefaultUtilities) { }
-    private readonly expressionsCompiler: IExpressionsCompiler = new ExpressionsCompiler(),
-  ) { }
 
   public createCompiledNestedCall(
     nestedFunction: FunctionCall,
@@ -22,18 +21,24 @@ export class NestedFunctionArgumentCompiler implements ArgumentCompiler {
       nestedFunction,
       parentFunction.args,
       context,
-      this.expressionsCompiler,
+      this.utilities,
     );
     const compiledCall = new ParsedFunctionCall(nestedFunction.functionName, compiledArgs);
     return compiledCall;
   }
 }
 
+interface ArgumentCompilationUtilities {
+  readonly expressionsCompiler: IExpressionsCompiler,
+  readonly wrapError: ErrorWithContextWrapper;
+  readonly createCallArgument: FunctionCallArgumentFactory;
+}
+
 function compileNestedFunctionArguments(
   nestedFunction: FunctionCall,
   parentFunctionArgs: IReadOnlyFunctionCallArgumentCollection,
   context: FunctionCallCompilationContext,
-  expressionsCompiler: IExpressionsCompiler,
+  utilities: ArgumentCompilationUtilities,
 ): IReadOnlyFunctionCallArgumentCollection {
   const requiredParameterNames = context
     .allFunctions
@@ -47,7 +52,7 @@ function compileNestedFunctionArguments(
         paramName,
         nestedFunction,
         parentFunctionArgs,
-        expressionsCompiler,
+        utilities,
       ),
     }))
     // Filter out arguments with absent values
@@ -67,7 +72,7 @@ function compileNestedFunctionArguments(
     .map(({
       parameterName,
       compiledArgumentValue,
-    }) => new FunctionCallArgument(parameterName, compiledArgumentValue));
+    }) => utilities.createCallArgument(parameterName, compiledArgumentValue));
   return buildArgumentCollectionFromArguments(compiledArguments);
 }
 
@@ -89,13 +94,13 @@ function compileArgument(
   parameterName: string,
   nestedFunction: FunctionCall,
   parentFunctionArgs: IReadOnlyFunctionCallArgumentCollection,
-  expressionsCompiler: IExpressionsCompiler,
+  utilities: ArgumentCompilationUtilities,
 ): string {
   try {
     const { argumentValue: codeInArgument } = nestedFunction.args.getArgument(parameterName);
-    return expressionsCompiler.compileExpressions(codeInArgument, parentFunctionArgs);
+    return utilities.expressionsCompiler.compileExpressions(codeInArgument, parentFunctionArgs);
-  } catch (err) {
+  } catch (error) {
-    throw new AggregateError([err], `Error when compiling argument for "${parameterName}"`);
+    throw utilities.wrapError(error, `Error when compiling argument for "${parameterName}"`);
   }
 }
 
@@ -107,3 +112,9 @@ function buildArgumentCollectionFromArguments(
     return compiledArgs;
   }, new FunctionCallArgumentCollection());
 }
+
+const DefaultUtilities: ArgumentCompilationUtilities = {
+  expressionsCompiler: new ExpressionsCompiler(),
+  wrapError: wrapErrorWithAdditionalContext,
+  createCallArgument: createFunctionCallArgument,
+};

src/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/SingleCall/Strategies/InlineFunctionCallCompiler.ts

@@ -1,8 +1,8 @@
-import { ExpressionsCompiler } from '@/application/Parser/Script/Compiler/Expressions/ExpressionsCompiler';
+import { ExpressionsCompiler } from '@/application/Parser/Executable/Script/Compiler/Expressions/ExpressionsCompiler';
-import type { IExpressionsCompiler } from '@/application/Parser/Script/Compiler/Expressions/IExpressionsCompiler';
+import type { IExpressionsCompiler } from '@/application/Parser/Executable/Script/Compiler/Expressions/IExpressionsCompiler';
-import { FunctionBodyType, type ISharedFunction } from '@/application/Parser/Script/Compiler/Function/ISharedFunction';
+import { FunctionBodyType, type ISharedFunction } from '@/application/Parser/Executable/Script/Compiler/Function/ISharedFunction';
-import type { FunctionCall } from '@/application/Parser/Script/Compiler/Function/Call/FunctionCall';
+import type { FunctionCall } from '@/application/Parser/Executable/Script/Compiler/Function/Call/FunctionCall';
-import type { CompiledCode } from '@/application/Parser/Script/Compiler/Function/Call/Compiler/CompiledCode';
+import type { CompiledCode } from '@/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/CompiledCode';
 import type { SingleCallCompilerStrategy } from '../SingleCallCompilerStrategy';
 
 export class InlineFunctionCallCompiler implements SingleCallCompilerStrategy {

src/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/SingleCall/Strategies/NestedFunctionCallCompiler.ts

@@ -1,14 +1,21 @@
-import { type CallFunctionBody, FunctionBodyType, type ISharedFunction } from '@/application/Parser/Script/Compiler/Function/ISharedFunction';
+import {
-import type { FunctionCall } from '@/application/Parser/Script/Compiler/Function/Call/FunctionCall';
+  type CallFunctionBody, FunctionBodyType,
-import type { FunctionCallCompilationContext } from '@/application/Parser/Script/Compiler/Function/Call/Compiler/FunctionCallCompilationContext';
+  type ISharedFunction,
-import type { CompiledCode } from '@/application/Parser/Script/Compiler/Function/Call/Compiler/CompiledCode';
+} from '@/application/Parser/Executable/Script/Compiler/Function/ISharedFunction';
+import type { FunctionCall } from '@/application/Parser/Executable/Script/Compiler/Function/Call/FunctionCall';
+import type { FunctionCallCompilationContext } from '@/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/FunctionCallCompilationContext';
+import type { CompiledCode } from '@/application/Parser/Executable/Script/Compiler/Function/Call/Compiler/CompiledCode';
+import { wrapErrorWithAdditionalContext, type ErrorWithContextWrapper } from '@/application/Parser/Common/ContextualError';
 import { NestedFunctionArgumentCompiler } from './Argument/NestedFunctionArgumentCompiler';
 import type { SingleCallCompilerStrategy } from '../SingleCallCompilerStrategy';
 import type { ArgumentCompiler } from './Argument/ArgumentCompiler';
 
 export class NestedFunctionCallCompiler implements SingleCallCompilerStrategy {
   public constructor(
-    private readonly argumentCompiler: ArgumentCompiler = new NestedFunctionArgumentCompiler(),
+    private readonly argumentCompiler: ArgumentCompiler
+    = new NestedFunctionArgumentCompiler(),
+    private readonly wrapError: ErrorWithContextWrapper
+    = wrapErrorWithAdditionalContext,
   ) {
   }
 
@@ -29,8 +36,11 @@ export class NestedFunctionCallCompiler implements SingleCallCompilerStrategy {
         const compiledNestedCall = context.singleCallCompiler
           .compileSingleCall(compiledParentCall, context);
         return compiledNestedCall;
-      } catch (err) {
+      } catch (error) {
-        throw new AggregateError([err], `Error with call to "${nestedCall.functionName}" function from "${callToFunction.functionName}" function`);
+        throw this.wrapError(
+          error,
+          `Failed to call '${nestedCall.functionName}' (callee function) from '${callToFunction.functionName}' (caller function).`,
+        );
       }
     }).flat();
   }

src/application/Parser/Executable/Script/Compiler/Function/Call/FunctionCallsParser.ts

@@ -0,0 +1,80 @@
+import type {
+  FunctionCallData,
+  FunctionCallsData,
+  FunctionCallParametersData,
+} from '@/application/collections/';
+import { isArray, isPlainObject } from '@/TypeHelpers';
+import { createTypeValidator, type TypeValidator } from '@/application/Parser/Common/TypeValidator';
+import { FunctionCallArgumentCollection } from './Argument/FunctionCallArgumentCollection';
+import { ParsedFunctionCall } from './ParsedFunctionCall';
+import { createFunctionCallArgument, type FunctionCallArgumentFactory } from './Argument/FunctionCallArgument';
+import type { FunctionCall } from './FunctionCall';
+
+export interface FunctionCallsParser {
+  (
+    calls: FunctionCallsData,
+    utilities?: FunctionCallParsingUtilities,
+  ): FunctionCall[];
+}
+
+interface FunctionCallParsingUtilities {
+  readonly typeValidator: TypeValidator;
+  readonly createCallArgument: FunctionCallArgumentFactory;
+}
+
+const DefaultUtilities: FunctionCallParsingUtilities = {
+  typeValidator: createTypeValidator(),
+  createCallArgument: createFunctionCallArgument,
+};
+
+export const parseFunctionCalls: FunctionCallsParser = (
+  calls,
+  utilities = DefaultUtilities,
+) => {
+  const sequence = getCallSequence(calls, utilities.typeValidator);
+  return sequence.map((call) => parseFunctionCall(call, utilities));
+};
+
+function getCallSequence(calls: FunctionCallsData, validator: TypeValidator): FunctionCallData[] {
+  if (!isPlainObject(calls) && !isArray(calls)) {
+    throw new Error('called function(s) must be an object or array');
+  }
+  if (isArray(calls)) {
+    validator.assertNonEmptyCollection({
+      value: calls,
+      valueName: 'function call sequence',
+    });
+    return calls as FunctionCallData[];
+  }
+  const singleCall = calls as FunctionCallData;
+  return [singleCall];
+}
+
+function parseFunctionCall(
+  call: FunctionCallData,
+  utilities: FunctionCallParsingUtilities,
+): FunctionCall {
+  utilities.typeValidator.assertObject({
+    value: call,
+    valueName: 'function call',
+    allowedProperties: ['function', 'parameters'],
+  });
+  const callArgs = parseArgs(call.parameters, utilities.createCallArgument);
+  return new ParsedFunctionCall(call.function, callArgs);
+}
+
+function parseArgs(
+  parameters: FunctionCallParametersData | undefined,
+  createArgument: FunctionCallArgumentFactory,
+): FunctionCallArgumentCollection {
+  const parametersMap = parameters ?? {};
+  return Object.keys(parametersMap)
+    .map((parameterName) => {
+      const argumentValue = parametersMap[parameterName];
+      return createArgument(parameterName, argumentValue);
+    })
+    .reduce((args, arg) => {
+      args.addArgument(arg);
+      return args;
+    }, new FunctionCallArgumentCollection());
+}

src/application/Parser/Executable/Script/Compiler/Function/Parameter/FunctionParameter.ts

@@ -1,4 +1,4 @@
-export interface IFunctionParameter {
+export interface FunctionParameter {
   readonly name: string;
   readonly isOptional: boolean;
 }

src/application/Parser/Executable/Script/Compiler/Function/Parameter/FunctionParameterCollection.ts

@@ -1,14 +1,14 @@
 import type { IFunctionParameterCollection } from './IFunctionParameterCollection';
-import type { IFunctionParameter } from './IFunctionParameter';
+import type { FunctionParameter } from './FunctionParameter';
 
 export class FunctionParameterCollection implements IFunctionParameterCollection {
-  private parameters = new Array<IFunctionParameter>();
+  private parameters = new Array<FunctionParameter>();
 
-  public get all(): readonly IFunctionParameter[] {
+  public get all(): readonly FunctionParameter[] {
     return this.parameters;
   }
 
-  public addParameter(parameter: IFunctionParameter) {
+  public addParameter(parameter: FunctionParameter) {
     this.ensureValidParameter(parameter);
     this.parameters.push(parameter);
   }
@@ -17,7 +17,7 @@ export class FunctionParameterCollection implements IFunctionParameterCollection
     return this.parameters.find((existingParameter) => existingParameter.name === name);
   }
 
-  private ensureValidParameter(parameter: IFunctionParameter) {
+  private ensureValidParameter(parameter: FunctionParameter) {
     if (this.includesName(parameter.name)) {
       throw new Error(`duplicate parameter name: "${parameter.name}"`);
     }

src/application/Parser/Executable/Script/Compiler/Function/Parameter/FunctionParameterCollectionFactory.ts

@@ -0,0 +1,12 @@
+import { FunctionParameterCollection } from './FunctionParameterCollection';
+import type { IFunctionParameterCollection } from './IFunctionParameterCollection';
+
+export interface FunctionParameterCollectionFactory {
+  (
+    ...args: ConstructorParameters<typeof FunctionParameterCollection>
+  ): IFunctionParameterCollection;
+}
+
+export const createFunctionParameterCollection: FunctionParameterCollectionFactory = (...args) => {
+  return new FunctionParameterCollection(...args);
+};

src/application/Parser/Executable/Script/Compiler/Function/Parameter/FunctionParameterParser.ts

@@ -0,0 +1,21 @@
+import type { ParameterDefinitionData } from '@/application/collections/';
+import { validateParameterName, type ParameterNameValidator } from '../Shared/ParameterNameValidator';
+import type { FunctionParameter } from './FunctionParameter';
+
+export interface FunctionParameterParser {
+  (
+    data: ParameterDefinitionData,
+    validator?: ParameterNameValidator,
+  ): FunctionParameter;
+}
+
+export const parseFunctionParameter: FunctionParameterParser = (
+  data,
+  validator = validateParameterName,
+) => {
+  validator(data.name);
+  return {
+    name: data.name,
+    isOptional: data.optional || false,
+  };
+};

src/application/Parser/Executable/Script/Compiler/Function/Parameter/IFunctionParameterCollection.ts

@@ -0,0 +1,9 @@
+import type { FunctionParameter } from './FunctionParameter';
+
+export interface IReadOnlyFunctionParameterCollection {
+  readonly all: readonly FunctionParameter[];
+}
+
+export interface IFunctionParameterCollection extends IReadOnlyFunctionParameterCollection {
+  addParameter(parameter: FunctionParameter): void;
+}

src/application/Parser/Executable/Script/Compiler/Function/Shared/ParameterNameValidator.ts

@@ -0,0 +1,22 @@
+import { createTypeValidator, type TypeValidator } from '@/application/Parser/Common/TypeValidator';
+
+export interface ParameterNameValidator {
+  (
+    parameterName: string,
+    typeValidator?: TypeValidator,
+  ): void;
+}
+
+export const validateParameterName = (
+  parameterName: string,
+  typeValidator = createTypeValidator(),
+) => {
+  typeValidator.assertNonEmptyString({
+    value: parameterName,
+    valueName: 'parameter name',
+    rule: {
+      expectedMatch: /^[0-9a-zA-Z]+$/,
+      errorMessage: `parameter name must be alphanumeric but it was "${parameterName}".`,
+    },
+  });
+};

src/application/Parser/Executable/Script/Compiler/Function/SharedFunctionCollection.ts

@@ -15,7 +15,7 @@ export class SharedFunctionCollection implements ISharedFunctionCollection {
     if (!name) { throw Error('missing function name'); }
     const func = this.functionsByName.get(name);
     if (!func) {
-      throw new Error(`called function is not defined "${name}"`);
+      throw new Error(`Called function is not defined: "${name}"`);
     }
     return func;
   }

src/application/Parser/Executable/Script/Compiler/Function/SharedFunctionsParser.ts

@@ -1,58 +1,79 @@
 import type {
-  FunctionData, CodeInstruction, CodeFunctionData, CallFunctionData, CallInstruction,
+  FunctionData, CodeInstruction, CodeFunctionData, CallFunctionData,
+  CallInstruction, ParameterDefinitionData,
 } from '@/application/collections/';
-import type { ILanguageSyntax } from '@/application/Parser/Script/Validation/Syntax/ILanguageSyntax';
+import type { ILanguageSyntax } from '@/application/Parser/Executable/Script/Validation/Syntax/ILanguageSyntax';
-import { CodeValidator } from '@/application/Parser/Script/Validation/CodeValidator';
+import { CodeValidator } from '@/application/Parser/Executable/Script/Validation/CodeValidator';
-import { NoEmptyLines } from '@/application/Parser/Script/Validation/Rules/NoEmptyLines';
+import { NoEmptyLines } from '@/application/Parser/Executable/Script/Validation/Rules/NoEmptyLines';
-import { NoDuplicatedLines } from '@/application/Parser/Script/Validation/Rules/NoDuplicatedLines';
+import { NoDuplicatedLines } from '@/application/Parser/Executable/Script/Validation/Rules/NoDuplicatedLines';
-import type { ICodeValidator } from '@/application/Parser/Script/Validation/ICodeValidator';
+import type { ICodeValidator } from '@/application/Parser/Executable/Script/Validation/ICodeValidator';
 import { isArray, isNullOrUndefined, isPlainObject } from '@/TypeHelpers';
+import { wrapErrorWithAdditionalContext, type ErrorWithContextWrapper } from '@/application/Parser/Common/ContextualError';
 import { createFunctionWithInlineCode, createCallerFunction } from './SharedFunction';
 import { SharedFunctionCollection } from './SharedFunctionCollection';
-import { FunctionParameter } from './Parameter/FunctionParameter';
+import { parseFunctionCalls, type FunctionCallsParser } from './Call/FunctionCallsParser';
-import { FunctionParameterCollection } from './Parameter/FunctionParameterCollection';
+import { createFunctionParameterCollection, type FunctionParameterCollectionFactory } from './Parameter/FunctionParameterCollectionFactory';
-import { parseFunctionCalls } from './Call/FunctionCallParser';
+import { parseFunctionParameter, type FunctionParameterParser } from './Parameter/FunctionParameterParser';
+import type { FunctionParameter } from './Parameter/FunctionParameter';
 import type { ISharedFunctionCollection } from './ISharedFunctionCollection';
-import type { ISharedFunctionsParser } from './ISharedFunctionsParser';
 import type { IReadOnlyFunctionParameterCollection } from './Parameter/IFunctionParameterCollection';
 import type { ISharedFunction } from './ISharedFunction';
 
-export class SharedFunctionsParser implements ISharedFunctionsParser {
+export interface SharedFunctionsParser {
-  public static readonly instance: ISharedFunctionsParser = new SharedFunctionsParser();
+  (
-
-  constructor(private readonly codeValidator: ICodeValidator = CodeValidator.instance) { }
-
-  public parseFunctions(
     functions: readonly FunctionData[],
     syntax: ILanguageSyntax,
-  ): ISharedFunctionCollection {
+    utilities?: SharedFunctionsParsingUtilities,
-    const collection = new SharedFunctionCollection();
+  ): ISharedFunctionCollection;
-    if (!functions.length) {
+}
-      return collection;
+
-    }
+export const parseSharedFunctions: SharedFunctionsParser = (
-    ensureValidFunctions(functions);
+  functions: readonly FunctionData[],
-    return functions
+  syntax: ILanguageSyntax,
-      .map((func) => parseFunction(func, syntax, this.codeValidator))
+  utilities = DefaultUtilities,
-      .reduce((acc, func) => {
+) => {
-        acc.addFunction(func);
+  const collection = new SharedFunctionCollection();
-        return acc;
+  if (!functions.length) {
-      }, collection);
+    return collection;
   }
+  ensureValidFunctions(functions);
+  return functions
+    .map((func) => parseFunction(func, syntax, utilities))
+    .reduce((acc, func) => {
+      acc.addFunction(func);
+      return acc;
+    }, collection);
+};
+
+const DefaultUtilities: SharedFunctionsParsingUtilities = {
+  wrapError: wrapErrorWithAdditionalContext,
+  parseParameter: parseFunctionParameter,
+  codeValidator: CodeValidator.instance,
+  createParameterCollection: createFunctionParameterCollection,
+  parseFunctionCalls,
+};
+
+interface SharedFunctionsParsingUtilities {
+  readonly wrapError: ErrorWithContextWrapper;
+  readonly parseParameter: FunctionParameterParser;
+  readonly codeValidator: ICodeValidator;
+  readonly createParameterCollection: FunctionParameterCollectionFactory;
+  readonly parseFunctionCalls: FunctionCallsParser;
 }
 
 function parseFunction(
   data: FunctionData,
   syntax: ILanguageSyntax,
-  validator: ICodeValidator,
+  utilities: SharedFunctionsParsingUtilities,
 ): ISharedFunction {
   const { name } = data;
-  const parameters = parseParameters(data);
+  const parameters = parseParameters(data, utilities);
   if (hasCode(data)) {
-    validateCode(data, syntax, validator);
+    validateCode(data, syntax, utilities.codeValidator);
     return createFunctionWithInlineCode(name, parameters, data.code, data.revertCode);
   }
   // Has call
-  const calls = parseFunctionCalls(data.call);
+  const calls = utilities.parseFunctionCalls(data.call);
   return createCallerFunction(name, parameters, calls);
 }
 
@@ -71,22 +92,35 @@ function validateCode(
     );
 }
 
-function parseParameters(data: FunctionData): IReadOnlyFunctionParameterCollection {
+function parseParameters(
+  data: FunctionData,
+  utilities: SharedFunctionsParsingUtilities,
+): IReadOnlyFunctionParameterCollection {
   return (data.parameters || [])
-    .map((parameter) => {
+    .map((parameter) => parseParameterWithContextualError(
-      try {
+      data.name,
-        return new FunctionParameter(
+      parameter,
-          parameter.name,
+      utilities,
-          parameter.optional || false,
+    ))
-        );
-      } catch (err) {
-        throw new Error(`"${data.name}": ${err.message}`);
-      }
-    })
     .reduce((parameters, parameter) => {
       parameters.addParameter(parameter);
       return parameters;
-    }, new FunctionParameterCollection());
+    }, utilities.createParameterCollection());
+}
+
+function parseParameterWithContextualError(
+  functionName: string,
+  parameterData: ParameterDefinitionData,
+  utilities: SharedFunctionsParsingUtilities,
+): FunctionParameter {
+  try {
+    return utilities.parseParameter(parameterData);
+  } catch (err) {
+    throw utilities.wrapError(
+      err,
+      `Failed to create parameter: ${parameterData.name} for function "${functionName}"`,
+    );
+  }
 }
 
 function hasCode(data: FunctionData): data is CodeFunctionData {

src/application/Parser/Executable/Script/Compiler/IScriptCompiler.ts

@@ -1,7 +1,7 @@
 import type { ScriptData } from '@/application/collections/';
-import type { IScriptCode } from '@/domain/IScriptCode';
+import type { ScriptCode } from '@/domain/Executables/Script/Code/ScriptCode';
 
 export interface IScriptCompiler {
   canCompile(script: ScriptData): boolean;
-  compile(script: ScriptData): IScriptCode;
+  compile(script: ScriptData): ScriptCode;
 }

src/application/Parser/Executable/Script/Compiler/ScriptCompiler.ts

@@ -0,0 +1,87 @@
+import type { FunctionData, ScriptData, CallInstruction } from '@/application/collections/';
+import type { ScriptCode } from '@/domain/Executables/Script/Code/ScriptCode';
+import type { ILanguageSyntax } from '@/application/Parser/Executable/Script/Validation/Syntax/ILanguageSyntax';
+import { CodeValidator } from '@/application/Parser/Executable/Script/Validation/CodeValidator';
+import { NoEmptyLines } from '@/application/Parser/Executable/Script/Validation/Rules/NoEmptyLines';
+import type { ICodeValidator } from '@/application/Parser/Executable/Script/Validation/ICodeValidator';
+import { wrapErrorWithAdditionalContext, type ErrorWithContextWrapper } from '@/application/Parser/Common/ContextualError';
+import { createScriptCode, type ScriptCodeFactory } from '@/domain/Executables/Script/Code/ScriptCodeFactory';
+import { FunctionCallSequenceCompiler } from './Function/Call/Compiler/FunctionCallSequenceCompiler';
+import { parseFunctionCalls } from './Function/Call/FunctionCallsParser';
+import { parseSharedFunctions, type SharedFunctionsParser } from './Function/SharedFunctionsParser';
+import type { CompiledCode } from './Function/Call/Compiler/CompiledCode';
+import type { IScriptCompiler } from './IScriptCompiler';
+import type { ISharedFunctionCollection } from './Function/ISharedFunctionCollection';
+import type { FunctionCallCompiler } from './Function/Call/Compiler/FunctionCallCompiler';
+
+interface ScriptCompilerUtilities {
+  readonly sharedFunctionsParser: SharedFunctionsParser;
+  readonly callCompiler: FunctionCallCompiler;
+  readonly codeValidator: ICodeValidator;
+  readonly wrapError: ErrorWithContextWrapper;
+  readonly scriptCodeFactory: ScriptCodeFactory;
+}
+
+const DefaultUtilities: ScriptCompilerUtilities = {
+  sharedFunctionsParser: parseSharedFunctions,
+  callCompiler: FunctionCallSequenceCompiler.instance,
+  codeValidator: CodeValidator.instance,
+  wrapError: wrapErrorWithAdditionalContext,
+  scriptCodeFactory: createScriptCode,
+};
+
+interface CategoryCollectionDataContext {
+  readonly functions: readonly FunctionData[];
+  readonly syntax: ILanguageSyntax;
+}
+
+export class ScriptCompiler implements IScriptCompiler {
+  private readonly functions: ISharedFunctionCollection;
+
+  constructor(
+    categoryContext: CategoryCollectionDataContext,
+    private readonly utilities: ScriptCompilerUtilities = DefaultUtilities,
+  ) {
+    this.functions = this.utilities.sharedFunctionsParser(
+      categoryContext.functions,
+      categoryContext.syntax,
+    );
+  }
+
+  public canCompile(script: ScriptData): boolean {
+    return hasCall(script);
+  }
+
+  public compile(script: ScriptData): ScriptCode {
+    try {
+      if (!hasCall(script)) {
+        throw new Error('Script does include any calls.');
+      }
+      const calls = parseFunctionCalls(script.call);
+      const compiledCode = this.utilities.callCompiler.compileFunctionCalls(calls, this.functions);
+      validateCompiledCode(compiledCode, this.utilities.codeValidator);
+      return this.utilities.scriptCodeFactory(
+        compiledCode.code,
+        compiledCode.revertCode,
+      );
+    } catch (error) {
+      throw this.utilities.wrapError(error, `Failed to compile script: ${script.name}`);
+    }
+  }
+}
+
+function validateCompiledCode(compiledCode: CompiledCode, validator: ICodeValidator): void {
+  [compiledCode.code, compiledCode.revertCode]
+    .filter((code): code is string => Boolean(code))
+    .map((code) => code as string)
+    .forEach(
+      (code) => validator.throwIfInvalid(
+        code,
+        [new NoEmptyLines()],
+      ),
+    );
+}
+
+function hasCall(data: ScriptData): data is ScriptData & CallInstruction {
+  return (data as CallInstruction).call !== undefined;
+}

src/application/Parser/Executable/Script/ScriptParser.ts

@@ -0,0 +1,151 @@
+import type { ScriptData, CodeScriptData, CallScriptData } from '@/application/collections/';
+import { NoEmptyLines } from '@/application/Parser/Executable/Script/Validation/Rules/NoEmptyLines';
+import type { ILanguageSyntax } from '@/application/Parser/Executable/Script/Validation/Syntax/ILanguageSyntax';
+import { CollectionScript } from '@/domain/Executables/Script/CollectionScript';
+import { RecommendationLevel } from '@/domain/Executables/Script/RecommendationLevel';
+import type { ScriptCode } from '@/domain/Executables/Script/Code/ScriptCode';
+import type { ICodeValidator } from '@/application/Parser/Executable/Script/Validation/ICodeValidator';
+import { wrapErrorWithAdditionalContext, type ErrorWithContextWrapper } from '@/application/Parser/Common/ContextualError';
+import type { ScriptCodeFactory } from '@/domain/Executables/Script/Code/ScriptCodeFactory';
+import { createScriptCode } from '@/domain/Executables/Script/Code/ScriptCodeFactory';
+import type { Script } from '@/domain/Executables/Script/Script';
+import { createEnumParser, type EnumParser } from '@/application/Common/Enum';
+import { parseDocs, type DocsParser } from '../DocumentationParser';
+import { ExecutableType } from '../Validation/ExecutableType';
+import { createExecutableDataValidator, type ExecutableValidator, type ExecutableValidatorFactory } from '../Validation/ExecutableValidator';
+import { CodeValidator } from './Validation/CodeValidator';
+import { NoDuplicatedLines } from './Validation/Rules/NoDuplicatedLines';
+import type { CategoryCollectionSpecificUtilities } from '../CategoryCollectionSpecificUtilities';
+
+export interface ScriptParser {
+  (
+    data: ScriptData,
+    collectionUtilities: CategoryCollectionSpecificUtilities,
+    scriptUtilities?: ScriptParserUtilities,
+  ): Script;
+}
+
+export const parseScript: ScriptParser = (
+  data,
+  collectionUtilities,
+  scriptUtilities = DefaultUtilities,
+) => {
+  const validator = scriptUtilities.createValidator({
+    type: ExecutableType.Script,
+    self: data,
+  });
+  validateScript(data, validator);
+  try {
+    const script = scriptUtilities.createScript({
+      name: data.name,
+      code: parseCode(
+        data,
+        collectionUtilities,
+        scriptUtilities.codeValidator,
+        scriptUtilities.createCode,
+      ),
+      docs: scriptUtilities.parseDocs(data),
+      level: parseLevel(data.recommend, scriptUtilities.levelParser),
+    });
+    return script;
+  } catch (error) {
+    throw scriptUtilities.wrapError(
+      error,
+      validator.createContextualErrorMessage('Failed to parse script.'),
+    );
+  }
+};
+
+function parseLevel(
+  level: string | undefined,
+  parser: EnumParser<RecommendationLevel>,
+): RecommendationLevel | undefined {
+  if (!level) {
+    return undefined;
+  }
+  return parser.parseEnum(level, 'level');
+}
+
+function parseCode(
+  script: ScriptData,
+  collectionUtilities: CategoryCollectionSpecificUtilities,
+  codeValidator: ICodeValidator,
+  createCode: ScriptCodeFactory,
+): ScriptCode {
+  if (collectionUtilities.compiler.canCompile(script)) {
+    return collectionUtilities.compiler.compile(script);
+  }
+  const codeScript = script as CodeScriptData; // Must be inline code if it cannot be compiled
+  const code = createCode(codeScript.code, codeScript.revertCode);
+  validateHardcodedCodeWithoutCalls(code, codeValidator, collectionUtilities.syntax);
+  return code;
+}
+
+function validateHardcodedCodeWithoutCalls(
+  scriptCode: ScriptCode,
+  validator: ICodeValidator,
+  syntax: ILanguageSyntax,
+) {
+  [scriptCode.execute, scriptCode.revert]
+    .filter((code): code is string => Boolean(code))
+    .forEach(
+      (code) => validator.throwIfInvalid(
+        code,
+        [new NoEmptyLines(), new NoDuplicatedLines(syntax)],
+      ),
+    );
+}
+
+function validateScript(
+  script: ScriptData,
+  validator: ExecutableValidator,
+): asserts script is NonNullable<ScriptData> {
+  validator.assertType((v) => v.assertObject<CallScriptData & CodeScriptData>({
+    value: script,
+    valueName: script.name ?? 'script',
+    allowedProperties: [
+      'name', 'recommend', 'code', 'revertCode', 'call', 'docs',
+    ],
+  }));
+  validator.assertValidName(script.name);
+  validator.assert(
+    () => Boolean((script as CodeScriptData).code || (script as CallScriptData).call),
+    'Neither "call" or "code" is defined.',
+  );
+  validator.assert(
+    () => !((script as CodeScriptData).code && (script as CallScriptData).call),
+    'Both "call" and "code" are defined.',
+  );
+  validator.assert(
+    () => !((script as CodeScriptData).revertCode && (script as CallScriptData).call),
+    'Both "call" and "revertCode" are defined.',
+  );
+}
+
+interface ScriptParserUtilities {
+  readonly levelParser: EnumParser<RecommendationLevel>;
+  readonly createScript: ScriptFactory;
+  readonly codeValidator: ICodeValidator;
+  readonly wrapError: ErrorWithContextWrapper;
+  readonly createValidator: ExecutableValidatorFactory;
+  readonly createCode: ScriptCodeFactory;
+  readonly parseDocs: DocsParser;
+}
+
+export type ScriptFactory = (
+  ...parameters: ConstructorParameters<typeof CollectionScript>
+) => Script;
+
+const createScript: ScriptFactory = (...parameters) => {
+  return new CollectionScript(...parameters);
+};
+
+const DefaultUtilities: ScriptParserUtilities = {
+  levelParser: createEnumParser(RecommendationLevel),
+  createScript,
+  codeValidator: CodeValidator.instance,
+  wrapError: wrapErrorWithAdditionalContext,
+  createValidator: createExecutableDataValidator,
+  createCode: createScriptCode,
+  parseDocs,
+};

src/application/Parser/Executable/Script/Validation/Rules/NoDuplicatedLines.ts

@@ -1,4 +1,4 @@
-import type { ILanguageSyntax } from '@/application/Parser/Script/Validation/Syntax/ILanguageSyntax';
+import type { ILanguageSyntax } from '@/application/Parser/Executable/Script/Validation/Syntax/ILanguageSyntax';
 import type { ICodeLine } from '../ICodeLine';
 import type { ICodeValidationRule, IInvalidCodeLine } from '../ICodeValidationRule';
 

src/application/Parser/Executable/Script/Validation/Syntax/BatchFileSyntax.ts

@@ -1,4 +1,4 @@
-import type { ILanguageSyntax } from '@/application/Parser/Script/Validation/Syntax/ILanguageSyntax';
+import type { ILanguageSyntax } from '@/application/Parser/Executable/Script/Validation/Syntax/ILanguageSyntax';
 
 const BatchFileCommonCodeParts = ['(', ')', 'else', '||'];
 const PowerShellCommonCodeParts = ['{', '}'];

src/application/Parser/Executable/Script/Validation/Syntax/ShellScriptSyntax.ts

@@ -1,4 +1,4 @@
-import type { ILanguageSyntax } from '@/application/Parser/Script/Validation/Syntax/ILanguageSyntax';
+import type { ILanguageSyntax } from '@/application/Parser/Executable/Script/Validation/Syntax/ILanguageSyntax';
 
 export class ShellScriptSyntax implements ILanguageSyntax {
   public readonly commentDelimiters = ['#'];