Refactoring: Define Blocktypes solely in Code

apps/docs/docs/dev/04-guides/06-jayvee-extensions.md

@@ -15,53 +15,38 @@ Jayvee extensions that shall be used by default are bundled into the so-called [
 
 A language extension defines meta information of block types which are required by the
 [language server](https://github.com/jvalue/jayvee/tree/main/libs/language-server).
-Such meta information describes properties of 
+Such meta information describes properties of
 block types such as their names, input / output types and their properties.
 
 Note that language extensions don't define any behavior. Instead, this is done by the corresponding execution extension.
 
 ### Execution extension
 
-An execution extension defines behavior for block types. They build on the meta information from the corresponding 
-language extension, e.g. input / output types of the block need to match the signature of the execution method and 
+An execution extension defines behavior for block types. They build on the meta information from the corresponding
+language extension, e.g. input / output types of the block need to match the signature of the execution method and
 properties are accessed by their specified name.
 
 Execution extensions are only required by the [interpreter](https://github.com/jvalue/jayvee/tree/main/apps/interpreter) and not necessarily by the [language server](https://github.com/jvalue/jayvee/tree/main/libs/language-server) as they solely define behavior.
 
 ## Recipes
 
-### Add a new Jayvee extension
+### Add a new Jayvee execution extension
 
-#### 1. Generate language and execution libraries
+#### 1. Generate an execution libraries
 
 ```bash
-npx nx g @nrwl/node:library --name="extensions/<extension-name>/lang"
 npx nx g @nrwl/node:library --name="extensions/<extension-name>/exec"
 ```
 
 #### 2. Create extension classes
 
-In `libs/extensions/<extension-name>/lang/src/extension.ts`:
-
-```typescript
-import {
-  BlockMetaInformation,
-  ConstructorClass,
-  JayveeLangExtension,
-} from '@jvalue/jayvee-language-server';
-
-export class MyLangExtension implements JayveeLangExtension {
-  getBlockMetaInf(): Array<ConstructorClass<BlockMetaInformation>> {
-    return [];
-  }
-}
-
-```
-
 In `libs/extensions/<extension-name>/exec/src/extension.ts`:
 
 ```typescript
-import { BlockExecutorClass, JayveeExecExtension } from '@jvalue/jayvee-execution';
+import {
+  BlockExecutorClass,
+  JayveeExecExtension,
+} from '@jvalue/jayvee-execution';
 
 export class MyExecExtension implements JayveeExecExtension {
   getBlockExecutors(): BlockExecutorClass[] {
@@ -72,12 +57,6 @@ export class MyExecExtension implements JayveeExecExtension {
 
 #### 3. Export extension classes
 
-In `libs/extensions/<extension-name>/lang/src/index.ts`:
-
-```typescript
-export * from './extension';
-```
-
 In `libs/extensions/<extension-name>/exec/src/index.ts`:
 
 ```typescript
@@ -86,25 +65,6 @@ export * from './extension';
 
 #### 4. Register new extension classes in the standard extension
 
-In `libs/extensions/std/lang/src/extension.ts`:
-
-```typescript
-// ...
-
-import { MyLangExtension } from '@jvalue/jayvee-extensions/<extension-name>/lang';
-
-export class StdLangExtension implements JayveeLangExtension {
-  private readonly wrappedExtensions: JayveeLangExtension[] = [
-    // ...
-    // Register your language extension here:
-    new MyLangExtension(),
-    // ...
-  ];
-
-  // ...
-}
-```
-
 In `libs/extensions/std/exec/src/extension.ts`:
 
 ```typescript
@@ -126,77 +86,28 @@ export class StdExecExtension implements JayveeExecExtension {
 
 ### Add a new block type in a Jayvee extension
 
-#### 1. Implement `BlockMetaInformation`
+#### 1. Create a builtin blocktype
 
-The following example defines a block type called `MyExtractor`. This block type, for instance, takes no input and 
-outputs a sheet. Furthermore, it defines two properties:
+Define the syntax of the new blocktype in the [language server's builtin blocktypes](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/stdlib/builtin-blocktypes).
 
-- `url` of type text
-- `limit` of type integer and default value `10`
-  - Considered optional due to the specified default value
+The following example defines a block type `MyExtractor` with a text property called `url` and a property `retries` with a default value:
 
-In `libs/extensions/<extension-name>/lang/src/lib/my-extractor-meta-inf.ts`:
+```jayvee
+builtin blocktype MyExtractor {
+	input default oftype None;
+	output default oftype Sheet;
 
-```typescript
-import {
-  BlockMetaInformation,
-  IOType,
-  PrimitiveValuetypes,
-} from '@jvalue/jayvee-language-server';
-
-export class MyExtractorMetaInformation extends BlockMetaInformation {
-  constructor() {
-    super(
-      // How the block type should be called:
-      'MyExtractor',
-
-      // Property definitions:
-      {
-        url: {
-          type: PrimitiveValuetypes.Text,
-        },
-        limit: {
-          type: PrimitiveValuetypes.Integer,
-          defaultValue: 10,
-        },
-      },
-
-      // Input type:
-      IOType.NONE,
-
-      // Output type:
-      IOType.SHEET,
-    );
-  }
+	property url oftype text;
+	property retries oftype interger: 10;
 }
 ```
 
-> **Note**
-> Use `IOType.NONE` whenever you expect no input or output:
->
-> - Use it as input type if you want to define an extractor
-> - Use it as output type if you want to define a loader
-
-#### 2. Register the new `BlockMetaInformation` in the language extension
+The new block type will be automatically registered on the language server startup.
 
-In `libs/extensions/<extension-name>/lang/src/extension.ts`:
+#### 2. Add custom validation logic (if required)
 
-```typescript
-// ...
-
-import { MyExtractorMetaInformation } from './lib/my-extractor-meta-inf';
+If the block type and/or its properties requires custom validation logic, you can implement it in the [language server's block type specific checks](https://github.com/jvalue/jayvee/tree/main/libs/language-server/src/lib/validation/checks/blocktype-specific).
 
-export class MyLangExtension implements JayveeLangExtension {
-  getBlockMetaInf(): Array<ConstructorClass<BlockMetaInformation>> {
-    return [
-      // ...
-      // Register your meta information here:
-      MyExtractorMetaInformation,
-      // ...
-    ];
-  }
-}
-```
 
 #### 3. Implement `BlockExecutor`
 
@@ -223,7 +134,7 @@ export class MyExtractorExecutor
 {
   // Needs to match the type in meta information:
   public static readonly type = 'MyExtractor';
-  
+
   public readonly inputType = IOType.NONE;
   public readonly outputType = IOType.SHEET;
 
@@ -240,7 +151,7 @@ export class MyExtractorExecutor
       'limit',
       PrimitiveValuetypes.Integer,
     );
-    
+
     // ...
 
     if (error) {

apps/docs/generator/src/main.ts

@@ -5,28 +5,38 @@
 import { readFileSync, readdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
-import { StdLangExtension } from '@jvalue/jayvee-extensions/std/lang';
 import {
+  JayveeServices,
   PrimitiveValuetypes,
-  getRegisteredBlockMetaInformation,
+  createJayveeServices,
+  getAllBuiltinBlocktypes,
   getRegisteredConstraintMetaInformation,
-  registerConstraints,
-  useExtension,
+  initializeWorkspace,
 } from '@jvalue/jayvee-language-server';
+import { NodeFileSystem } from 'langium/node';
 
 import { UserDocGenerator } from './user-doc-generator';
 
-useExtension(new StdLangExtension());
-
-function main(): void {
+async function main(): Promise<void> {
   const rootPath = join(__dirname, '..', '..', '..', '..');
-  generateBlockTypeDocs(rootPath);
-  generateConstraintTypeDocs(rootPath);
-  generateValueTypeDocs(rootPath);
+
+  const services = createJayveeServices(NodeFileSystem).Jayvee;
+  await initializeWorkspace(services);
+
+  generateBlockTypeDocs(services, rootPath);
+  generateConstraintTypeDocs(services, rootPath);
+  generateValueTypeDocs(services, rootPath);
   generateExampleDocs(rootPath);
 }
 
-function generateBlockTypeDocs(rootPath: string): void {
+function generateBlockTypeDocs(
+  services: JayveeServices,
+  rootPath: string,
+): void {
+  const metaInfs = getAllBuiltinBlocktypes(
+    services.shared.workspace.LangiumDocuments,
+  );
+
   const docsPath = join(
     rootPath,
     'apps',
@@ -35,9 +45,9 @@ function generateBlockTypeDocs(rootPath: string): void {
     'user',
     'block-types',
   );
-  const metaInfs = getRegisteredBlockMetaInformation();
+
   for (const metaInf of metaInfs) {
-    const userDocBuilder = new UserDocGenerator();
+    const userDocBuilder = new UserDocGenerator(services);
     const blockTypeDoc = userDocBuilder.generateBlockTypeDoc(metaInf);
 
     const fileName = `${metaInf.type}.md`;
@@ -48,7 +58,10 @@ function generateBlockTypeDocs(rootPath: string): void {
   }
 }
 
-function generateConstraintTypeDocs(rootPath: string): void {
+function generateConstraintTypeDocs(
+  services: JayveeServices,
+  rootPath: string,
+): void {
   const docsPath = join(
     rootPath,
     'apps',
@@ -57,11 +70,10 @@ function generateConstraintTypeDocs(rootPath: string): void {
     'user',
     'constraint-types',
   );
-  registerConstraints();
   const metaInfs = getRegisteredConstraintMetaInformation();
 
   for (const metaInf of metaInfs) {
-    const userDocBuilder = new UserDocGenerator();
+    const userDocBuilder = new UserDocGenerator(services);
     const blockTypeDoc = userDocBuilder.generateConstraintTypeDoc(metaInf);
 
     const fileName = `${metaInf.type}.md`;
@@ -72,9 +84,12 @@ function generateConstraintTypeDocs(rootPath: string): void {
   }
 }
 
-function generateValueTypeDocs(rootPath: string): void {
+function generateValueTypeDocs(
+  services: JayveeServices,
+  rootPath: string,
+): void {
   const docsPath = join(rootPath, 'apps', 'docs', 'docs', 'user', 'valuetypes');
-  const userDocBuilder = new UserDocGenerator();
+  const userDocBuilder = new UserDocGenerator(services);
   const valueTypeDoc =
     userDocBuilder.generateValueTypesDoc(PrimitiveValuetypes);
 
@@ -113,4 +128,6 @@ ${exampleModel.toString()}
   }
 }
 
-main();
+main()
+  .then(() => console.log('Finished generating docs!'))
+  .catch((e) => console.error(e));