@bentley/app-schema-validator 0.2.191

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright © 2025 Bentley Systems, Incorporated. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# app-schema-validator
+
+Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.
+
+The purpose of this NPM CLI tool is to validate the schemas present within an application installer. It locates the schemas present in the extracted installer and perform the validations.
+
+## Getting Started
+
+### Prerequisites
+
+- [Node](https://nodejs.org/en/): an installation of the latest security patch of Node 20. The Node installation also includes the **npm** package manager.
+
+### Installation
+
+Install globally:
+
+```sh
+npm install -g @bentley/app-schema-validator
+```
+
+### Validating an application schemas
+
+Following are the arguments required:
+
+- **-i, --installerDir**: Path to the extracted installer.
+
+- **-b, --baseSchemaRefDir**: Root directory of all released schemas (root of bis-schemas repo).
+
+- **-o, --output**: The path where output files will be generated.
+
+For help use the '**-h**' option.
+
+#### Sample Command:
+
+```sh
+app-schema-validator -i D:\\\\dir1\\\\extracted\\app -b D:\\\\dir1\\\\bis-schemas -o D:\\\\dir1\\\\output
+```
+
+### Updating to newer version
+
+Since the package is installed globally, updating has a different syntax than normal. To update the package globally, run:
+
+```sh
+npm update -g @bentley/app-schema-validator
+```

package/bin/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* Licensed under the MIT License. See LICENSE.md in the project root for license terms.
+*--------------------------------------------------------------------------------------------*/
+
+const fs = require("fs");
+const commander = require("commander");
+const getResults = require("@bentley/imodel-schema-validator").getResults;
+const verifyAppSchemas = require("../lib/AppSchemaValidator").verifyAppSchemas;
+
+const program = new commander.Command("App-Schema-Validator NPM CLI");
+program.option("-i, --installerDir <required>", "Path to the extracted installer.");
+program.option("-b, --baseSchemaRefDir <required>", "Root directory of all released schemas (root of bis-schemas repo).");
+program.option("-o, --output <required>", "Path where output files will be generated.");
+
+program.parse(process.argv);
+
+async function validate() {
+  if (process.argv.length != 8) {
+    console.log("usage : index.js");
+    console.log("   -i, --installerDir                      :Path to the extracted installer.");
+    console.log("   -b, --baseSchemaRefDir                  :Root directory of all released schemas (root of bis-schemas repo).");
+    console.log("   -o, --output                            :Path where output files will be generated.");
+    throw new Error("Missing from required arguments and their values.");
+  }
+
+  if (!program.installerDir || !program.baseSchemaRefDir || !program.output) {
+    console.log(chalk.default.red("Invalid input. For help use the '-h' option."));
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(program.installerDir)) {
+    const error = "App installer directory do not exist: " + program.installerDir;
+    throw new Error(error);
+  }
+
+  if (!fs.existsSync(program.baseSchemaRefDir)) {
+    const error = "The baseSchemaRefDir do not exist: " + program.baseSchemaRefDir;
+    throw new Error(error);
+  }
+
+  try {
+    const results = await verifyAppSchemas(program.installerDir, program.baseSchemaRefDir, program.output);
+    await getResults(results, program.baseSchemaRefDir, program.output);
+    process.exit(0);
+  } catch (err) {
+    console.log(err);
+    process.exit(1);
+  }
+}
+
+validate().then()
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });

package/lib/AppSchemaValidator.d.ts

@@ -0,0 +1,16 @@
+import { IModelValidationResult } from "@bentley/imodel-schema-validator";
+/**
+ * Verifies an App Schemas
+ * @param appDirectory Path to the extracted installer directory
+ * @param baseSchemaRefDir Path to the bis-schemas directory
+ * @param output Path to the output directory
+ * @returns Array of validation results
+ */
+export declare function verifyAppSchemas(appDirectory: string, baseSchemaRefDir: string, output: string): Promise<IModelValidationResult[]>;
+/**
+ * Find directories where schema files are present
+ * @param appDirectory Directory to search for schema files
+ * @returns Array of paths where schema files are found
+ */
+export declare function generateAppSchemaDirectoryList(appDirectory: string): Promise<string[]>;
+//# sourceMappingURL=AppSchemaValidator.d.ts.map

package/lib/AppSchemaValidator.js

@@ -0,0 +1,131 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* Licensed under the MIT License. See LICENSE.md in the project root for license terms.
+*--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAppSchemaDirectoryList = exports.verifyAppSchemas = void 0;
+const fs = require("fs");
+const path = require("path");
+const chalk = require("chalk");
+const readdirp = require("readdirp");
+const Reporter_1 = require("@bentley/imodel-schema-validator/lib/Reporter");
+const ecschema_locaters_1 = require("@itwin/ecschema-locaters");
+const utils_1 = require("./utils");
+const imodel_schema_validator_1 = require("@bentley/imodel-schema-validator");
+/**
+ * Verifies an App Schemas
+ * @param appDirectory Path to the extracted installer directory
+ * @param baseSchemaRefDir Path to the bis-schemas directory
+ * @param output Path to the output directory
+ * @returns Array of validation results
+ */
+async function verifyAppSchemas(appDirectory, baseSchemaRefDir, output) {
+    const results = [];
+    const releasedSchemaDirectories = await (0, utils_1.generateSchemaDirectoryLists)(baseSchemaRefDir);
+    const appSchemaDirs = await generateAppSchemaDirectoryList(appDirectory);
+    const excludeSchemas = await (0, utils_1.getExcludeSchemaList)();
+    for (const appSchemaDir of appSchemaDirs) {
+        for (const appSchemaFile of fs.readdirSync(appSchemaDir)) {
+            if (!appSchemaFile.endsWith(".ecschema.xml"))
+                continue;
+            if (await (0, utils_1.shouldExcludeSchema)(appSchemaFile, excludeSchemas))
+                continue;
+            const validationResult = await applyValidations(appSchemaDir, appSchemaFile, appSchemaDirs, releasedSchemaDirectories, output);
+            results.push(validationResult);
+        }
+    }
+    return results;
+}
+exports.verifyAppSchemas = verifyAppSchemas;
+/**
+ * Apply all validations
+ * @param schemaDir Directory where schema is located
+ * @param schemaFile The schema file
+ * @param appSchemaDirs List of paths where app schemas are located
+ * @param releasedSchemaDirectories List of paths where released schemas are located
+ * @param output Path to the output directory
+ * @returns Validation result of a schema
+ */
+async function applyValidations(schemaDir, schemaFile, appSchemaDirs, releasedSchemaDirectories, output) {
+    const appSchemaPath = path.join(schemaDir, schemaFile);
+    const appSchemaKey = await getSchemaInfo(appSchemaPath);
+    const name = appSchemaKey.name;
+    const version = appSchemaKey.version.toString();
+    const validationResult = { name, version };
+    console.log("\nBEGIN VALIDATION AND DIFFERENCE AUDIT: %s.%s", name, version);
+    Reporter_1.Reporter.writeToLogFile(name, version, `BEGIN VALIDATION AND DIFFERENCE AUDIT: ${name}.${version}\n`, output);
+    await (0, imodel_schema_validator_1.validateSchema)(name, version, appSchemaPath, releasedSchemaDirectories, validationResult, output);
+    releasedSchemaDirectories = fixReleasedSchemaDirectories(schemaDir, releasedSchemaDirectories);
+    if ((0, imodel_schema_validator_1.isDynamicSchema)(appSchemaPath)) {
+        console.log(chalk.default.grey(`Skipping difference audit for ${name} ${version}.
+    The schema is a dynamic schema and released versions of dynamic schemas are not saved.`));
+        Reporter_1.Reporter.writeToLogFile(name, version, `Skipping difference audit for ${name}.${version}.
+    The schema is a dynamic schema and released versions of dynamic schemas are not saved.\n`, output);
+        validationResult.comparer = imodel_schema_validator_1.iModelValidationResultTypes.Skipped;
+        validationResult.approval = imodel_schema_validator_1.iModelValidationResultTypes.Skipped;
+    }
+    else {
+        let releasedSchemaPath = "";
+        // Find out Difference
+        for (const dir of releasedSchemaDirectories) {
+            fs.readdirSync(dir).forEach((releasedSchemaFile) => {
+                if (releasedSchemaFile.toLowerCase().includes(appSchemaKey.toString().toLowerCase())) {
+                    releasedSchemaPath = path.join(dir, releasedSchemaFile);
+                }
+            });
+        }
+        if (!releasedSchemaPath) {
+            if ((0, imodel_schema_validator_1.isDynamicSchema)(appSchemaPath)) {
+                console.log(chalk.default.grey("Skipping difference audit for ", name, version, ". No released schema found."));
+                Reporter_1.Reporter.writeToLogFile(name, version, `Skipping difference audit for ${name}.${version}. No released schema found.\n`, output);
+                validationResult.comparer = imodel_schema_validator_1.iModelValidationResultTypes.Skipped;
+            }
+            else {
+                console.log(chalk.default.grey("Skipping difference audit for ", name, version, ". No released schema found."));
+                Reporter_1.Reporter.writeToLogFile(name, version, `Skipping difference audit for ${name}.${version}. No released schema found.\n`, output);
+                validationResult.comparer = imodel_schema_validator_1.iModelValidationResultTypes.NotFound;
+            }
+        }
+        else {
+            // The app installer (opensiteplus) is missing several reference schemas. We provide those from bis-schemas.
+            const appSchemaReferences = [...appSchemaDirs, ...releasedSchemaDirectories];
+            await (0, imodel_schema_validator_1.compareSchema)(name, version, appSchemaPath, releasedSchemaPath, appSchemaReferences, releasedSchemaDirectories, output, validationResult);
+            releasedSchemaDirectories = fixReleasedSchemaDirectories(schemaDir, releasedSchemaDirectories);
+        }
+    }
+    console.log("END VALIDATION AND DIFFERENCE AUDIT: ", name, version);
+    Reporter_1.Reporter.writeToLogFile(name, version, `END VALIDATION AND DIFFERENCE AUDIT: ${name}.${version}\n`, output);
+    return validationResult;
+}
+/**
+ * Retrieves schema information
+ * @param schemaXMLFilePath Path of schema XML file
+ * @returns SchemaKey object containing the schema information
+ */
+async function getSchemaInfo(schemaXMLFilePath) {
+    const schemaXml = fs.readFileSync(schemaXMLFilePath, "utf-8");
+    const locater = new ecschema_locaters_1.StubSchemaXmlFileLocater();
+    return locater.getSchemaKey(schemaXml);
+}
+function fixReleasedSchemaDirectories(appSchemaDir, releasedSchemaDirectories) {
+    // @bentley/schema-comparer and @bentley/schema-validator are pushing the input schema path to reference array.
+    // Removing this path to fix the bug in finding releasedSchemaFile
+    const index = releasedSchemaDirectories.indexOf(appSchemaDir);
+    if (index !== -1)
+        releasedSchemaDirectories.splice(index, 1);
+    return releasedSchemaDirectories;
+}
+/**
+ * Find directories where schema files are present
+ * @param appDirectory Directory to search for schema files
+ * @returns Array of paths where schema files are found
+ */
+async function generateAppSchemaDirectoryList(appDirectory) {
+    // Skip schemas from platform based licensing-addon e.g licensing-win32-x64
+    const filter = { fileFilter: "*.ecschema.xml", directoryFilter: ["!.vscode", "!licensing-*"] };
+    const schemaPaths = (await readdirp.promise(appDirectory, filter)).map((entry) => path.dirname(entry.fullPath));
+    return Array.from(new Set(schemaPaths).keys());
+}
+exports.generateAppSchemaDirectoryList = generateAppSchemaDirectoryList;
+//# sourceMappingURL=AppSchemaValidator.js.map

package/lib/ignoreSchemaList.json

@@ -0,0 +1,97 @@
+[
+  {
+    "name": "ChangedElements",
+    "version": "01.00.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "ECDbChange",
+    "version": "01.00.01",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "USCustomaryUnitSystemDefaults",
+    "version": "01.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "Unit_Attributes",
+    "version": "01.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "Units_Schema",
+    "version": "01.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "SIUnitSystemDefaults",
+    "version": "01.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "rdl_customAttributes",
+    "version": "01.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "KindOfQuantity_Schema",
+    "version": "01.01",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "iip_mdb_customAttributes",
+    "version": "01.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "EditorCustomAttributes",
+    "version": "01.03",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "Dimension_Schema",
+    "version": "01.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "Bentley_Standard_CustomAttributes",
+    "version": "01.14",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "Bentley_Standard_Classes",
+    "version": "01.01",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "Bentley_ECSchemaMap",
+    "version": "01.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "Bentley_Common_Classes",
+    "version": "01.01",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "MetaSchema_V3Conversion",
+    "version": "02.04",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "ECDbMap",
+    "version": "01.00",
+    "reason": "EC2 schema from imodel-native repository"
+  },
+  {
+    "name": "IModelChange",
+    "version": "02.00.00",
+    "reason": "It is not inserted into the iModel"
+  },
+  {
+    "name": "SchemaLocalizationCustomAttributes",
+    "version": "01.00.00",
+    "reason": "This schema version is released but not approved"
+  }
+]

package/lib/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Find released schemas directories
+ * @schemaDirectory Directory to search for schema files
+ * @returns Array containing released schemas directories
+ */
+export declare function generateSchemaDirectoryLists(schemaDirectory: string): Promise<string[]>;
+/**
+ * Provides a list of schemas to exclude from validation
+ */
+export declare function getExcludeSchemaList(): Promise<any>;
+/**
+ * Checks if a schema should be excluded from validation
+ * @param schemaFle Schema file
+ * @param excludeList List of schemas to exclude
+ * @returns True if schema should be excluded, false otherwise
+ */
+export declare function shouldExcludeSchema(schemaFle: string, excludeList: any[]): Promise<boolean>;
+//# sourceMappingURL=utils.d.ts.map

package/lib/utils.js

@@ -0,0 +1,54 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* Licensed under the MIT License. See LICENSE.md in the project root for license terms.
+*--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldExcludeSchema = exports.getExcludeSchemaList = exports.generateSchemaDirectoryLists = void 0;
+const fs = require("fs");
+const path = require("path");
+const readdirp = require("readdirp");
+/**
+ * Find released schemas directories
+ * @schemaDirectory Directory to search for schema files
+ * @returns Array containing released schemas directories
+ */
+async function generateSchemaDirectoryLists(schemaDirectory) {
+    const filter = { fileFilter: "*.ecschema.xml", directoryFilter: ["!node_modules", "!.vscode", "!tools"] };
+    const allSchemaDirs = (await readdirp.promise(schemaDirectory, filter)).map((schemaPath) => path.dirname(schemaPath.fullPath));
+    return Array.from(new Set(allSchemaDirs.filter((schemaDir) => /released/i.test(schemaDir))).keys());
+}
+exports.generateSchemaDirectoryLists = generateSchemaDirectoryLists;
+/**
+ * Provides a list of schemas to exclude from validation
+ */
+async function getExcludeSchemaList() {
+    const ignoreListJson = path.resolve(__dirname, "./ignoreSchemaList.json");
+    if (!fs.existsSync(ignoreListJson)) {
+        console.log("File not found: ", ignoreListJson);
+        return;
+    }
+    const rawdata = fs.readFileSync(ignoreListJson, "utf8");
+    const schemas = JSON.parse(rawdata);
+    return schemas;
+}
+exports.getExcludeSchemaList = getExcludeSchemaList;
+/**
+ * Checks if a schema should be excluded from validation
+ * @param schemaFle Schema file
+ * @param excludeList List of schemas to exclude
+ * @returns True if schema should be excluded, false otherwise
+ */
+async function shouldExcludeSchema(schemaFle, excludeList) {
+    const rawData = schemaFle.split(".");
+    const schemaName = rawData[0];
+    const schemaVersion = rawData.slice(1, -2).join(".");
+    const matches = excludeList.filter((s) => s.name.toLowerCase() === schemaName.toLowerCase());
+    if (matches.length === 0)
+        return false;
+    if (matches.some((s) => s.version === schemaVersion))
+        return true;
+    return false;
+}
+exports.shouldExcludeSchema = shouldExcludeSchema;
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@bentley/app-schema-validator",
+  "description": "This tool validates schemas present in an application's installer",
+  "main": "./lib/AppSchemaValidator.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iTwin/bis-schema-validation"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Bentley Systems, Inc.",
+    "url": "http://www.bentley.com"
+  },
+  "version": "0.2.191",
+  "bin": {
+    "app-schema-validator": "./bin/index.js"
+  },
+  "dependencies": {
+    "@itwin/ecschema-locaters": "4.10.10",
+    "@itwin/ecschema-metadata": "4.10.10",
+    "@bentley/imodel-schema-validator": "0.2.191",
+    "chalk": "^2.4.1",
+    "commander": "^2.19.0",
+    "readdirp": "^3.0.0",
+    "rimraf": "^3.0.2"
+  },
+  "devDependencies": {
+    "@itwin/eslint-plugin": "^4.0.2",
+    "@itwin/build-tools": "4.10.10",
+    "@types/node": "~18.16.20",
+    "@types/chai": "4.3.1",
+    "@types/mocha": "^10.0.6",
+    "cpx2": "^3.0.0",
+    "typescript": "~5.3.3",
+    "chai": "^4.3.10",
+    "mocha": "^10.2.0",
+    "nyc": "^15.1.0",
+    "eslint": "^8.56.0"
+  },
+  "scripts": {
+    "build": "tsc 1>&2 && npm run copy:assets && npm run copy:test-assets",
+    "lint": "eslint -f visualstudio \"./src/**/*.ts\" 1>&2",
+    "test": "mocha --timeout=999999999 --check-leaks --global _playwrightInstance",
+    "cover": "nyc npm -s test",
+    "clean": "rimraf lib",
+    "copy:assets": "cpx ./ignoreSchemaList.json ./lib",
+    "copy:test-assets": "cpx \"./src/test/assets/**/*\" ./lib/test/assets"
+  }
+}