feat: add core tools

2026-02-27 19:32:12 +00:00 · 2018-12-18 17:41:03 +01:00
commit 1ac90ef633
23 changed files with 3788 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,134 @@
+# @openstapps/core-tools
+
+[![pipeline status](https://img.shields.io/gitlab/pipeline/openstapps/core-tools.svg?style=flat-square)](https://gitlab.com/openstapps/core-tools/commits/master) 
+[![npm](https://img.shields.io/npm/v/@openstapps/core-tools.svg?style=flat-square)](https://npmjs.com/package/@openstapps/core-tools)
+[![license)](https://img.shields.io/npm/l/@openstapps/core-tools.svg?style=flat-square)](https://www.gnu.org/licenses/gpl-3.0.en.html)
+[![documentation](https://img.shields.io/badge/documentation-online-blue.svg?style=flat-square)](https://openstapps.gitlab.io/core-tools)
+
+Tools to convert and validate StAppsCore
+
+## What are the tools for?
+
+The StAppsCore Converter is a tool for converting SC-types (TypeScript) into JSON schema files.
+
+JSON schema files are needed for run-time validation of SC-type objects, as this is a tedious task to do using SC-types defined in TypeScript (not possible without additional coding). That said, StAppsCore Converter practically prepares SC-types to be used for object validation (determining whether a JavaScript/JSON object is a valid object of the corresponding SC-type) using StAppsCore Validator.
+
+The StAppsCore Validator is a tool for run-time validation of objects (determining whether a JavaScript/JSON object is a valid object of the corresponding SC-type. It consumes JSON schema files from StAppsCore as the definitions of SC-types against which are validated concrete (actual) objects (as an example SCDish object in the example below).
+
+## Installation 
+
+Installation of the npm package (using `npm install`) makes the tool available as an executable with the name `openstapps-core-tools`.
+
+## How to use the converter?
+
+Add `@validatable` to the Typedoc comment of the types that you want to convert to JSONSchema.
+
+The command `openstapps-core-tools` can then be called using these arguments:
+
+```shell
+node_modules/.bin/openstapps-core-tools schema <srcPath> <schemaPath>
+```
+where:
+- `<srcPath>` is path to the project (where used `*.ts` files are, e.g. `src/core`,
+- `<schemaPath>` is directory to save output files to, e.g. `lib/schema`.
+
+Complete command with the example arguments is then:
+```shell
+node_modules/.bin/openstapps-core-tools src/core lib/schema
+```
+
+Inside of a script in `package.json` or if the npm package is installed globally, the tool `stapps-convert` can be called without its local path (`node_modules/.bin`):
+
+```shell
+openstapps-core-tools src/core lib/schema
+```
+
+## How to use the validator?
+
+### Using the validator programatically
+
+```typescript
+import {Validator} from '@openstapps/core-tools';
+import {SCDish} from '@openstapps/core';
+import {ValidatorResult} from 'jsonschema';
+import {join} from 'path';
+
+const objectToValidate: SCDish = {
+type: 'Dish',
+// more properties
+};
+
+// instantiate a new validator
+const validator = new Validator();
+
+// make the validator read the schema files
+validator.addSchemas(join('node_modules', '@openstapps', 'core', 'lib', 'schema'));
+
+// validate an object
+const result: ValidatorResult = validator.validate(objectToValidate);
+```
+
+#### Using validateFiles function
+
+The JSON files passed to the validateFiles method have an added layer.
+That layer encapsulates the actual JSON data of the object to be verified and adds a property to enable true negative testing.
+
+Your basic JSON object:
+
+```json
+{
+  "property1": "value1",
+  "property2": "value2",
+  ...
+}
+```
+
+JSON for validateFiles:
+```json
+{
+  "errorNames": [],
+  "instance": {
+    "property1": "value1",
+    "property2": "value2",
+    ...
+  },
+  "schema": "NameOfSchema"
+}
+```
+
+Where `errorNames` holds the string values of the name property of the expected ValidationErrors from JSON Schema. Empty array means no errors are expected.
+
+`schema` holds the name of the schema to validate the instance against.
+
+### How to use validator as a CLI tool (executable)?
+
+The command `openstapps-core-tools` can then be called using these arguments:
+
+```shell
+node_modules/.bin/openstapps-core-tools validate <schemaPath> <testPath> [reportPath]
+```
+where:
+- `<schemaPath>` is a directory where JSON schema files are, e.g. `lib/schema`,
+- `<testPath>` is a directory where test files are, e.g. `src/test/resources`,
+- `[reportPath]` is a file where the HTML report of the validation will be saved to, e.g. `report.html` (optional argument - if it's not provided no report will be written).
+
+Command with the example arguments is then for example:
+```shell
+node_modules/.bin/openstapps-validate lib/schema src/test/resources
+```
+
+Inside of a script in `package.json` or if the npm package is installed globally, the tool `openstapps-validate` can be called without its local path (`node_modules/.bin`):
+
+```shell
+openstapps-validate lib/schema src/test/resources report.html
+```
+
+## Generate documentation for routes
+
+To generate a documentation for the routes use the following command in the root directory of your StAppsCore.
+
+The generator relies on dynamic imports and must therefore be run this way.
+
+```shell
+node --require ts-node/register node_modules/@openstapps/core-tools/src/cli.ts routes PATH/TO/ROUTES.md
+```