Merge pull request #504 from jvalue/v0.3.0

Release v0.3.0

apps/docs/versioned_docs/version-0.3.0/dev/01-intro.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 1
+---
+
+# Introduction for Jayvee Developers
+
+## How to contribute
+
+In order to contribute to the Jayvee project, please have a look at our [contribution guide](https://github.com/jvalue/jayvee/blob/main/CONTRIBUTING.md). Before planning a contribution, please read the [design principles](./05-design-principles.md) and consider if your changes fit the vision expressed there.
+
+The overall project is licensed under the `AGPL-3.0-only` license and is compliant to the [REUSE Specification](https://reuse.software/spec/) by the [Free Software Foundation Europe](https://fsfe.org/).
+Because of this, contributions are required to adhere to the license and follow that specification.
+More details on this topic can be found [here](./02-dev-processes/03-licensing-and-copyright.md).
+
+And last but not least, please read and follow our [code of conduct](https://github.com/jvalue/jayvee/blob/main/CODE_OF_CONDUCT.md).
+
+## Project overview
+
+The Jayvee repository is located [here](https://github.com/jvalue/jayvee) on GitHub.
+It uses an [Nx mono-repository](https://nx.dev/) setup and contains all related projects, most notably the Jayvee language server and interpreter.
+Please have a look at the [architecture overview](./03-architecture-overview.md) for more details.
+
+## Prerequisites
+
+Node.js and npm are required for development.
+It is recommended to use their LTS version to avoid any potential compatibility issues.
+Also, refer to this [quick start guide](https://github.com/jvalue/jayvee#development-quickstart) for developers.
+
+In order to run the Jayvee VS Code extension during development, VS Code is required as IDE.
+Using VS Code also allows installing the [Langium VS Code extension](https://marketplace.visualstudio.com/items?itemName=langium.langium-vscode) for better IDE support when working with Langium grammar files.
+
+## Resources for getting started
+
+### Langium
+
+- [**Langium documentation**](https://langium.org/docs/)
+- Practical examples using Langium:
+  - [Langium examples](https://github.com/langium/langium/tree/main/examples): Official example languages by Langium
+  - [Langium's grammar language](https://github.com/langium/langium/tree/main/packages/langium): The implementation of Langium's own grammar language
+  - [Language server for SQL](https://github.com/langium/langium-sql): An implementation of a language server for SQL
+  - [MiniLogo DSL](https://github.com/langium/langium-minilogo): A domain-specific language for drawing pictures
+  - [Lox language](https://github.com/langium/langium-lox): An implementation of the Lox scripting language (also see the "Crafting Interpreters" book below)
+  - [SimpleUI DSL](https://github.com/TypeFox/langium-ui-framework): A domain-specific language for generating user interfaces
+  - [STPA-DSL](https://github.com/kieler/stpa): A domain-specific language for System-Theoretic Process Analysis
+- [Langium playground](https://langium.org/playground/): A tool for testing Langium grammars and visualizing resulting ASTs
+- [Typefox blog](https://www.typefox.io/blog/): A blog by the company behind Langium, mostly posting Langium-related content.
+
+### Building compilers / interpreters / DSLs
+
+- [Crafting Interpreters](https://craftinginterpreters.com/contents.html): A book by Robert Nystrom on implementing an interpreter for the Lox scripting language
+- [DSL Engineering](https://voelter.de/dslbook/markusvoelter-dslengineering-1.0.pdf): A book by Markus Voelter on designing, implementing and using domain-specific languages
+- [Awesome Compilers](https://github.com/aalhour/awesome-compilers#readme): A list featuring many resources on compilers and interpreters

apps/docs/versioned_docs/version-0.3.0/dev/01-intro.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/01-rfc-process.md

@@ -0,0 +1,13 @@
+---
+title: Language Design Process (RFCs)
+sidebar_position: 1
+---
+
+We use RFCs to discuss changes to the language before implementing them. You can have a look at all closed (accepted / rejected) RFCs [here](https://github.com/jvalue/jayvee/pulls?q=is%3Apr+is%3Aclosed+RFC+), and all RFCs under discussion [here](https://github.com/jvalue/jayvee/pulls?q=is%3Apr+is%3Aopen+RFC).
+
+If you want to contribute an RFC please follow these steps:
+1. Make a copy of the **template** at `rfc/0000-rfc-template.md` and place it into the `rfc` folder.
+2. Create a draft for the RFC on a new branch. Follow the `TODOs` in template to do so.
+3. Open a pull request with prefix `RFC <number>` in the title.
+4. Address the reviews. Consider opening a new PR if major things need to be addressed and the discussion log becomes too confusing.
+5. Once accepted, create an issue with the necessary steps to implement the RFC.

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/01-rfc-process.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/02-debug-vs-code-extension.md

@@ -0,0 +1,25 @@
+---
+title: Debugging via the VS Code extension
+sidebar_position: 2
+---
+
+The VS Code extension of Jayvee can be used to interactively debug the language server.
+During development, when using VS Code as IDE, another instance of VS Code can be opened which has the most recent, locally built VS Code extension loaded.
+This can be achieved using the launch configuration `Run extension` the `Run and Debug` side-menu of VS Code or by pressing the `F5` key if that launch configuration is already selected there.
+
+Note that there is no file watching mechanism involved.
+So in order to reflect changes to the source code, the additional VS Code instance has to be **closed and reopened** as described above.
+
+## How to attach a debugger
+
+1. Use the launch configuration `Run extension` to open the additional VS Code instance with the extension loaded
+2. Use the launch configuration `Attach to Language Server` to attach the debugger
+
+Any set breakpoints should now be marked as active and pause the execution once they are reached.
+
+## How to view logs of the language server
+
+In the additional VS Code instance, it is possible to view the logs of the language server.
+They might also be helpful for debugging since any uncaught errors are logged with their stack trace by the Langium framework.
+
+To view the logs, open the bottom panel called `Output` and select `Jayvee` in the dropdown menu.

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/02-debug-vs-code-extension.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/03-licensing-and-copyright.md

@@ -0,0 +1,69 @@
+---
+title: Licensing and copyright
+sidebar_position: 3
+---
+
+The [Jayvee repository](https://github.com/jvalue/jayvee) is REUSE compliant, meaning that it fulfills the 
+[REUSE Specification](https://reuse.software/spec/) by the [Free Software Foundation Europe](https://fsfe.org/) (FSFE).
+This makes clear under which license each project file is licensed under and who owns the copyright, not only for 
+humans but also for machines.
+
+This is done by explicitly adding copyright and licensing information to each file of the project. This is achieved 
+by either using a comment header or a separate `*.license` file in case comments are not possible.
+
+See <https://reuse.software/> more information.
+
+## What license is used in this project and who is the copyright holder?
+
+The entire project is licensed under [AGPL-3.0-only](https://spdx.org/licenses/AGPL-3.0-only.html), the
+license file can be found [here](https://github.com/jvalue/jayvee/blob/main/LICENSES/AGPL-3.0-only.txt).
+The copyright holder is the [Friedrich-Alexander-Universität Erlangen-Nürnberg](https://www.fau.eu/).
+
+## How to submit a REUSE compliant contribution?
+
+In case you want to contribute to the project, you will need to ensure that all of your contributed files are REUSE 
+compliant. In order to achieve this, you need to add a key-value pair for both copyright and licensing information 
+following this schema:
+
+```
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
+```
+
+In case a file allows comments, use single-line comments to add the copyright and licensing information at the top 
+of the file. Otherwise, create a corresponding `*.license` file with the text above as its content. You can have a 
+look at some existing project files to get an impression on it is done in practice.
+
+For files with common file extensions, you can use the [reuse CLI tool](https://github.com/fsfe/reuse-tool) to add 
+licensing and copyright information automatically.
+
+For more details, you can have a look at the [Getting Started tutorial](https://reuse.software/tutorial/) on the REUSE 
+website.
+
+## How to validate REUSE compliance?
+
+When you make a contribution and open a new pull request, the CI checks whether your contribution is REUSE compliant 
+using the [reuse CLI tool](https://github.com/fsfe/reuse-tool).
+
+In order to validate REUSE compliance in your local development environment, you have to install the
+[reuse CLI tool](https://github.com/fsfe/reuse-tool) and run the following command in the projects' root folder:
+
+```bash
+reuse lint
+```
+
+You can also set up a pre-commit hook, so the above command is run before each commit.
+See [here](https://reuse.readthedocs.io/en/latest/readme.html#run-as-pre-commit-hook) for details on how to set it up.
+
+## How to hide `*.license` files in IDEs
+
+During development, the file explorer of your IDE may be cluttered due to the numerous `*.license` files in the 
+project. Luckily, most IDEs allow hiding certain files, e.g. by specifying a pattern to exclude them from the 
+explorer.
+
+Below, you can find instructions on how to hide `*.license` files in commonly used IDEs:
+- **Visual Studio Code**: Add `**/*.license` to the
+[`files.exclude` setting](https://code.visualstudio.com/docs/getstarted/userinterface#_explorer) 
+- **WebStorm**: Add `*.license` to the
+[excluded files setting](https://www.jetbrains.com/help/webstorm/configuring-project-structure.html#exclude-by-pattern)

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/03-licensing-and-copyright.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/04-release-jayvee-version.md

@@ -0,0 +1,22 @@
+---
+title: Releasing a new Jayvee version
+sidebar_position: 4
+---
+
+## Version Numbers
+
+In this early stage of the project we do not yet follow [semantic versioning](https://semver.org/) since we expect the introduction of breaking changes frequently.
+To indicate that, we only release alpha versions where the `version` is incremented with every release.
+- For the npm packages, we use the version `0.0.<version>`.
+- For the GitHub releases, we use the git tag `v0.0.<version>-alpha`.
+
+## Jayvee Release Procedure
+
+For releasing a new version of Jayvee, you need to complete the following steps:
+
+1. Increment the version in the `package.json` file.
+2. Run `npm i` to update the `package-lock.json`.
+3. Run `npx nx run docs:version-snapshot` to generate a snapshot of the docs for the previous version.
+4. If you are on a feature or dev branch, merge into main.
+5. Create a GitHub release on the main branch. Attach a changelog.
+6. The CI/CD will deal with the rest.

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/04-release-jayvee-version.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Development Process",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Here you can find general processes around developing Jayvee."
+  }
+}

apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/_category_.json.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.3.0/dev/03-architecture-overview.md

@@ -0,0 +1,43 @@
+---
+title: Architecture overview
+sidebar_position: 4
+---
+
+Jayvee has a clear separation between the language itself and its execution.
+This guide gives an overview of the overall architecture.
+
+## Language Server
+
+On the pure language side, the central project is the [language server](https://github.com/jvalue/jayvee/tree/main/libs/language-server) which is heavily built upon the [Langium framework](https://langium.org/).
+It contains the syntax definition (i.e. the grammar) and is capable of performing static semantic analysis on models, so invalid models can be rejected and errors are reported to the user.
+It uses the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) for communicating with IDEs in order to provide common features such as diagnostics, auto completion and much more.
+
+## Interpreter
+
+The Jayvee [interpreter](https://github.com/jvalue/jayvee/tree/main/apps/interpreter) on the other hand is capable of running Jayvee models.
+Therefore, it uses the language server as a library to perform lexing, parsing and semantic analysis on given models.
+In case no errors were found during these phases, it executes the model by interpreting it.
+This means that models are not compiled to any other language, like a compiler does, but rather directly executed on the fly without any code generation involved.
+The interpreter comes with a command-line interface (CLI) for users, so they are able to execute Jayvee models easily.
+
+The following diagram visualizes the architecture described so far:
+
+```mermaid
+graph LR
+model[Jayvee Model] --> lexical(Lexical Analysis)
+subgraph Jayvee Interpreter
+    subgraph Jayvee Language Server
+        subgraph Langium Framework
+            lexical --> syntax(Syntax Analysis)
+        end
+        syntax --> semantic(Semantic Analysis)
+    end
+    semantic --> interpretation(Interpretation)
+end
+```
+
+## Jayvee Extensions
+
+Lastly, there are Jayvee extensions for adding additional features to Jayvee.
+See [here](./04-guides/06-jayvee-extensions.md) for more details.
+It is worth pointing out that extensions also follow the separation between language and execution described above.

apps/docs/versioned_docs/version-0.3.0/dev/03-architecture-overview.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/versioned_docs/version-0.3.0/dev/04-guides/01-jayvee-grammar.md

@@ -0,0 +1,34 @@
+---
+title: The Jayvee grammar
+sidebar_position: 1
+---
+
+The grammar of Jayvee describes the syntax and structure of the language.
+It is located in the language server project.
+The grammar itself is written in [Langium's own grammar language](https://langium.org/docs/grammar-language/) which is similar to [Xtext](https://www.eclipse.org/Xtext/) grammars.
+Such grammar files are easily identifiable via their `.langium` file extension.
+
+The grammar is used to generate TypeScript interfaces that represent the Abstract Syntax Tree (AST) and different, semantically equivalent files to define syntax highlighting for different applications.
+For instance, a [TextMate](https://macromates.com/manual/en/language_grammars) file is generated for the syntax highlighting in the Jayvee VS Code extension whereas a [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) file is generated for the syntax highlighting in the Monaco editor.
+
+For further information on the grammar language of Langium, visit the corresponding [Langium documentation](https://langium.org/docs/grammar-language/).
+
+## Working with the grammar
+
+To run the code generation, either use `npm run generate` for solely the code generation or `npm run build` for an entire build. The code generation also generates further code, like the standard library. 
+
+Whenever the grammar is changed and the code generation is run during development, it is advisory to **close and reopen the IDE**, so the changes are noticed and the file indexing is updated.
+
+## How to rename AST nodes
+
+Renaming AST nodes is not as straight forward as one might initially assume.
+When renaming individual rules in the grammar, just the generated TypeScript code in `ast.ts` will reflect the renaming, but not the rest of the codebase.
+
+The following steps explain how to rename an AST node, so the change is reflected in the entire codebase. As an example, an AST node called `A` is supposed to be renamed to `B`:
+
+- Open the `ast.ts` file in the language server project
+- Locate the `A` interface / type and the `isA` typeguard
+- Use the rename feature by the IDE to perform the renaming from `A` to `B` and from `isA` to `isB`
+- Open the grammar and locate the `A` rule
+- Use the rename feature by the Langium VS Code extension to perform the renaming from `A` to `B`
+- Run `npm run generate`

apps/docs/versioned_docs/version-0.3.0/dev/04-guides/01-jayvee-grammar.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only