ci: Enable schema build for monorepo (#1206)

JIRA: CPOUI5FOUNDATION-1162

+ Schema build script moved to `internal/documentation/scripts/`
- allows a parameter to set if schema should be based on local state or
latest published npm state
+ npm scripts for this regard moved to `internal/documentation/`
+ Deployment CI jobs adjusted (but still disabled till final v5 release)
+ Changes in local workspace will be reflected in local build of schema
    - CI will generate schemas based on latest published npm version

Author: maxreichmann

.github/workflows/deploy-vitepress-docs.yaml

@@ -59,10 +59,9 @@ jobs:
             - name: Build jsdoc
               working-directory: internal/documentation
               run: npm run jsdoc-generate
-            # TODO: Skip for now deployment of the schema until we do a Schema Version 5 release
-            # - name: Build Sch3 |
-            #       npm run schema-generate
-            #       npm run schema-workspace-generate
+            - name: Build Schema
+              working-directory: internal/documentation
+              run: npm run schema-generate
             - name: Checkout gh-pages
               uses: actions/checkout@v5
               with:
@@ -72,7 +71,7 @@ jobs:
               run: |
                   # TODO: Skip for now deployment of the schema until we do a Schema Version 5 release
                   # rm -rf ./gh-pages/schema
-                  # cp -R ./site/schema ./gh-pages/
+                  # cp -R internal/documentation/schema ./gh-pages/schema/
                   rm -rf ./gh-pages/${DOC_VERSION}
                   rm -rf ./gh-pages/${DOC_ALIAS}
 

.github/workflows/github-ci.yml

@@ -44,6 +44,7 @@ jobs:
       run: npm run jsdoc-generate
 
     - name: Generate merged JSON schema
+      working-directory: internal/documentation
       run: npm run schema-generate
 
     - name: Generate CLI documentation

.gitignore

@@ -67,3 +67,4 @@ internal/documentation/docs/pages/CLI.md
 internal/documentation/.vitepress/dist
 internal/documentation/.vitepress/cache
 internal/documentation/dist
+internal/documentation/schema/*

internal/documentation/package.json

@@ -32,7 +32,9 @@
 		"jsdoc": "npm run jsdoc-generate && open-cli dist/api/index.html",
 		"jsdoc-generate": "jsdoc -c jsdoc/jsdoc.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)",
 		"jsdoc-generate-workspace": "jsdoc -c jsdoc/jsdoc-workspace.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)",
-		"generate-cli-doc": "node ./scripts/generateCliDoc.js"
+		"generate-cli-doc": "node ./scripts/generateCliDoc.js",
+		"schema-generate": "node ./scripts/buildSchema.js @ui5/project-npm",
+		"schema-generate-workspace": "node ./scripts/buildSchema.js @ui5/project"
 	},
 	"dependencies": {
 		"@types/node": "^22.5.1",
@@ -46,15 +48,17 @@
 		"vue": "^3.4.38"
 	},
 	"devDependencies": {
+		"@apidevtools/json-schema-ref-parser": "^14.2.1",
 		"@ui5/builder-npm": "npm:@ui5/builder@^4.0.11",
 		"@ui5/cli-npm": "npm:@ui5/cli@^4.0.26",
 		"@ui5/fs-npm": "npm:@ui5/fs@^4.0.2",
 		"@ui5/logger-npm": "npm:@ui5/logger@^4.0.2",
 		"@ui5/project-npm": "npm:@ui5/project@^4.0.6",
 		"@ui5/server-npm": "npm:@ui5/server@^4.0.7",
 		"docdash": "^2.0.2",
+		"handlebars": "^4.7.8",
 		"jsdoc": "^4.0.4",
 		"open-cli": "^8.0.0",
-		"handlebars": "^4.7.8"
+		"traverse": "^0.6.11"
 	}
 }

internal/documentation/scripts/buildSchema.js

@@ -0,0 +1,61 @@
+import path from "node:path";
+import {fileURLToPath} from "node:url";
+import {writeFile, mkdir} from "node:fs/promises";
+import {$RefParser} from "@apidevtools/json-schema-ref-parser";
+import traverse from "traverse";
+
+// Read the given CLI parameter to set which UI5/project version to use.
+// Default to "@ui5/project-npm" to use the latest published version (for Github Pages).
+// For testing, the local version can be used by providing "@ui5/project".
+// Example: node buildSchema.js @ui5/project-npm
+// Example: node buildSchema.js @ui5/project
+const UI5_PROJECT_VERSION = process.argv[2] || "@ui5/project-npm";
+
+try {
+	// Use ui5.yaml.json and ui5-workspace.yaml.json
+	const schemaNames = ["ui5", "ui5-workspace"];
+
+	schemaNames.forEach(async (schemaName) => {
+		const SOURCE_SCHEMA_PATH = fileURLToPath(
+			new URL(`./lib/validation/schema/${schemaName}.json`,
+				import.meta.resolve(`${UI5_PROJECT_VERSION}/package.json`))
+		);
+		const TARGET_SCHEMA_PATH = fileURLToPath(
+			new URL(`../schema/${schemaName}.yaml.json`, import.meta.url)
+		);
+
+		const parser = new $RefParser();
+		const schema = await parser.bundle(SOURCE_SCHEMA_PATH);
+
+		// Remove $id from all nodes and $schema / $comment from all except the root node.
+		// Defining $id on the root is not required and as the URL will be a different one it might even cause issues.
+		// $schema only needs to be defined once per file.
+		traverse(schema).forEach(function(v) {
+			// eslint-disable-next-line no-invalid-this
+			const traverseContext = this;
+			if (v && typeof v === "object" && !Array.isArray(v)) {
+				if (v.$id) {
+					delete v.$id;
+				}
+				if (!traverseContext.isRoot) {
+					if (v.$schema) {
+						delete v.$schema;
+					}
+					if (v.$comment) {
+						delete v.$comment;
+					}
+				}
+				traverseContext.update(v);
+			}
+		});
+
+		await mkdir(path.dirname(TARGET_SCHEMA_PATH), {recursive: true});
+		await writeFile(TARGET_SCHEMA_PATH, JSON.stringify(schema, null, 2));
+
+		console.log(`Wrote bundled ${schemaName}.yaml schema file to ${TARGET_SCHEMA_PATH}`);
+	});
+} catch (error) {
+	console.log(error);
+	process.exit(1);
+}
+

package-lock.json

@@ -28,8 +28,6 @@
 		"lint:commit": "commitlint",
 		"unit": "npm run unit --workspaces --if-present",
 		"coverage": "npm run coverage --workspaces --if-present",
-		"schema-generate": "node ./scripts/buildSchema.js ui5",
-		"schema-workspace-generate": "node ./scripts/buildSchema.js ui5-workspace",
 		"depcheck": "depcheck --ignores @ui5/builder,@ui5/cli,@ui5/fs,@ui5/logger,@ui5/project,@ui5/server,local-web-server,@commitlint/config-conventional,husky && npm run depcheck --workspaces --if-present",
 		"check-licenses": "licensee --errors-only",
 		"generate-cli-doc": "npm run generate-cli-doc --workspace=@ui5/documentation"
@@ -43,7 +41,6 @@
 		"@ui5/project": "^4.0.6"
 	},
 	"devDependencies": {
-		"@apidevtools/json-schema-ref-parser": "^14.2.1",
 		"@commitlint/cli": "^20.1.0",
 		"@commitlint/config-conventional": "^20.0.0",
 		"@eslint/js": "^9.8.0",
@@ -55,8 +52,7 @@
 		"globals": "^16.4.0",
 		"husky": "^9.1.7",
 		"licensee": "^11.1.1",
-		"local-web-server": "^5.4.0",
-		"traverse": "^0.6.11"
+		"local-web-server": "^5.4.0"
 	},
 	"workspaces": [
 		"packages/*",