convention_builder 1.8.6 → 2.0.0

package/README.md

@@ -3,4 +3,16 @@
   This library is the main code component in our `farmos_convention_publisher` project.
   It allows a user to create complex Farm data schemata using the FarmOs entities, which are already abstracted into JSON Schema files.
   The objects that abstract this process have many added functionalities, such as the generation of rich react documentation, standalone schema validators and versioning.
-  
+
+# Some Characteristics
+
+## Versioning
+
+  Al conventions and overlays are fully versioned.
+
+  This implies a version attribute in the defining object will ensure they are stored in a subfolder with the version name inside the adequate folder (with the convention/overlay name) in the `outputs` section.
+
+  The assumed way to store versions is by using git tags.
+
+  The rebuild scripts will grab each tag for each convention and build all versions using the mentioned subfolders.
+

package/dist/module/index.js

@@ -9089,6 +9089,28 @@ var require_schema_utilities = __commonJS({
       return `https://gitlab.com/api/v4/projects/${projectID}/jobs/artifacts/main/raw/input/collection/${type}/${bundle}/schema.json?job=copy_schemas`;
     }
     __name(basicSchemaURLTemplate, "basicSchemaURLTemplate");
+    function compareSemvers(semverA, semverB) {
+      let aFields = semverA.split(".").map((d) => parseInt(d));
+      let bFields = semverB.split(".").map((d) => parseInt(d));
+      let output = 0;
+      [0, 1, 2].forEach((fieldIndex) => {
+        if (output != 0) {
+          return;
+        }
+        ;
+        if (aFields[fieldIndex] != bFields[fieldIndex]) {
+          output = aFields[fieldIndex] > bFields[fieldIndex] ? 1 : -1;
+        }
+        ;
+      });
+      return output;
+    }
+    __name(compareSemvers, "compareSemvers");
+    function findLatestSemverString(semverStringArray) {
+      let sorted = semverStringArray.sort((a, b) => compareSemvers(b, a));
+      return sorted[0];
+    }
+    __name(findLatestSemverString, "findLatestSemverString");
     exports.dig = dig;
     exports.bury = bury;
     exports.fixRelationshipDataField = fixRelationshipDataField;
@@ -9114,6 +9136,8 @@ var require_schema_utilities = __commonJS({
     exports.gitlabConventionURLTemplate = gitlabConventionURLTemplate;
     exports.gitlabOverlayURLTemplate = gitlabOverlayURLTemplate;
     exports.basicSchemaURLTemplate = basicSchemaURLTemplate;
+    exports.compareSemvers = compareSemvers;
+    exports.findLatestSemverString = findLatestSemverString;
   }
 });
 
@@ -10469,7 +10493,8 @@ var require_convention_builder = __commonJS({
       gitlabConventionURLTemplate,
       basicSchemaURLTemplate,
       arrayToStructuredConvention,
-      flattenJSONSchema
+      flattenJSONSchema,
+      findLatestSemverString
     } = require_schema_utilities();
     var papa = require_papaparse();
     function getAttributes(root, convention) {
@@ -10483,6 +10508,7 @@ var require_convention_builder = __commonJS({
       constructor({
         typeAndBundle,
         name,
+        version,
         validExamples,
         erroredExamples,
         repoURLTemplateFunction = gitlabOverlayURLTemplate,
@@ -10499,6 +10525,7 @@ var require_convention_builder = __commonJS({
         deletedAttributes = []
       }) {
         this.name = name;
+        this.version = version;
         this.typeAndBundle = typeAndBundle;
         this.validExamples = validExamples;
         this.erroredExamples = erroredExamples;
@@ -10773,14 +10800,14 @@ var require_convention_builder = __commonJS({
        */
       store(test = true) {
         this.updateSchema();
-        let targetPath = `${this.storagePath()}/${this.schemaName}`;
+        let targetPath = `${this.storagePath()}/${this.schemaName}/${this.version}/`;
         if (!this.trivial) {
           fs.mkdirSync(targetPath, { recursive: true }, console.error);
           fs.mkdirSync(`${targetPath}/examples/correct`, { recursive: true }, console.error);
           fs.mkdirSync(`${targetPath}/examples/incorrect`, { recursive: true }, console.error);
         }
         let valid = "not tested";
-        if (test) {
+        if (test && !this.trivial) {
           let test2 = this.testExamples();
           valid = test2.success;
           if (!valid) {
@@ -11001,16 +11028,21 @@ var require_convention_builder = __commonJS({
        * Adds an attribute which should be an entity represented as a schema overlay object.
        * @param {SchemaOverlay|String} schemaOverlayObject -- An object of the SchemaOverlay class or a string. If it is a string, it should be the "type--bundle" class of the desired base FarmOS schema or a preexisting overlay, using the name it's contained folder has in "collection/overlays".
        * @param {string} attributeName -- Name identifying the entity inside the schema. Typically it is not the type--bundle pair but a unique name related to its functionality inside the schema. An example would be the case in which a convention involves many quantities: you can't name each quantity "quantity", instead the logical naming pattern is alluding to what's being measured.
+       * @param {SemVer} version -- In case of string, you can indicate the version, otherwise the latest one will be used.
        * @param {boolean} required -- Indicate wether the attribute should be marked as 'required' by the schema, in which case every submission lacking this attribute will be marked as rejected.
        */
-      addAttribute({ schemaOverlayObject, attributeName, required }) {
+      addAttribute({ schemaOverlayObject, attributeName, version, required }) {
         let overlaysOnly = process.argv.includes("overlaysOnly");
         if (typeof schemaOverlayObject == "string") {
           let schemaOverlayName = schemaOverlayObject;
           let isOverlay = fs.readdirSync(`${this.storagePath()}/overlays`).find((folder) => folder == schemaOverlayObject);
           if (isOverlay) {
             try {
-              schemaOverlayObject = new SchemaOverlay(JSON.parse(fs.readFileSync(`${this.storagePath()}/overlays/${schemaOverlayObject}/object.json`)));
+              if (!version) {
+                let versions = fs.readdirSync(`${this.storagePath()}/overlays/${schemaOverlayObject}`, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name);
+                version = findLatestSemverString(versions);
+              }
+              schemaOverlayObject = new SchemaOverlay(JSON.parse(fs.readFileSync(`${this.storagePath()}/overlays/${schemaOverlayObject}/${version}/object.json`)));
               schemaOverlayObject.global = true;
             } catch (e) {
               if (e.code == "ENOENT" && !overlaysOnly) {
@@ -11047,6 +11079,9 @@ var require_convention_builder = __commonJS({
           schemaOverlayObject.updateSchema();
         }
         ;
+        if (!schemaOverlayObject.version) {
+          schemaOverlayObject.version = this.version;
+        }
         this.overlays[attributeName] = schemaOverlayObject;
         if (required) {
           this.required.push(attributeName);
@@ -11080,6 +11115,14 @@ var require_convention_builder = __commonJS({
         this.relationships.push({ containerEntity, relationName, mentionedEntity, required });
         this.updateSchema();
       }
+      /**
+       * Removes overlay from the convention, as well as all relationships in it or mentioning it.
+       * @param {} attributeName
+       */
+      removeOverlay(attributeName) {
+        this.relatioships = this.relationships.filter((rel) => rel.containerEntitiy != attributeName && rel.mentionedEntity != attributeName);
+        delete this.overlays[attributeName];
+      }
       /**
        * Organizes all attributes of a convention into a hierarchical binary tree, under the assumption the tree is binary.
        * @param {ConventionSchema} -- convention
@@ -11167,8 +11210,8 @@ var require_convention_builder = __commonJS({
        */
       document() {
         let header = `import CodeBlock from '@theme/CodeBlock';
-import Schema from "@site/static/schemas/${this.schemaName}/schema.json";
-import SchemaReduced from "@site/static/schemas/${this.schemaName}/schema_required_only.json";
+import Schema from "@site/static/schemas/${this.schemaName}/${this.version}/schema.json";
+import SchemaReduced from "@site/static/schemas/${this.schemaName}/${this.version}/schema_required_only.json";
 import JSONSchemaViewer from "@theme/JSONSchemaViewer";
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -11338,10 +11381,22 @@ import TabItem from '@theme/TabItem';
       getTabularRepresentation() {
         return flattenJSONSchema(this.schema, true);
       }
+      /**
+       * If no examples have been added by hand, will grab examples from the default folders in the definition's subdirectory.
+       */
+      addDefaultFolderExamples() {
+        if (!this.validExamples) {
+          this.addExample({ path: `${__dirname}/examples/correct` });
+        }
+        if (!this.erroredExamples) {
+          this.addExample({ path: `${__dirname}/examples/incorrect` });
+        }
+      }
       /**
        * Build an AJV validator and ensure all valid examples are accepted and all error examples are rejected. Returns an array attribute for each set of examples, plus a general success attribute indicating wether all examples resulted as expected and a failedExamples array only listing entities for which there was no success (meanin unrejected error examples and rejected valid examples).
        */
       testExamples() {
+        this.addDefaultFolderExamples();
         let generalOutput = {};
         if (!this.validExamples || !this.erroredExamples) {
           throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute. Valid examples amount: ${this.validExamples ? this.validExamples.length : "validExamples is not an array"}, errored examples amount: ${this.erroredExamples ? this.erroredExamples.length : "erroredExamples is not an array"}.`);
@@ -11420,10 +11475,10 @@ import TabItem from '@theme/TabItem';
           return output2;
         }
         ;
-        let targetPath = `${this.storagePath()}/conventions/${this.schemaName}`;
+        let targetPath = `${this.storagePath()}/conventions/${this.schemaName}/${this.version}`;
         let mainEntityType = this.schemaName.split("--")[0];
         let documentationFolder = `${this.storagePath()}/../documentation/Conventions/${mainEntityType}`;
-        let documentationPath = `${documentationFolder}/${this.schemaName}.mdx`;
+        let documentationPath = `${documentationFolder}/${this.schemaName}_${this.version}.mdx`;
         fs.mkdirSync(targetPath, { recursive: true }, console.error);
         fs.mkdirSync(`${targetPath}/examples/correct`, { recursive: true }, console.error);
         fs.mkdirSync(`${targetPath}/examples/incorrect`, { recursive: true }, console.error);

package/dist/node/index.js

@@ -9083,6 +9083,28 @@ var require_schema_utilities = __commonJS({
       return `https://gitlab.com/api/v4/projects/${projectID}/jobs/artifacts/main/raw/input/collection/${type}/${bundle}/schema.json?job=copy_schemas`;
     }
     __name(basicSchemaURLTemplate, "basicSchemaURLTemplate");
+    function compareSemvers(semverA, semverB) {
+      let aFields = semverA.split(".").map((d) => parseInt(d));
+      let bFields = semverB.split(".").map((d) => parseInt(d));
+      let output = 0;
+      [0, 1, 2].forEach((fieldIndex) => {
+        if (output != 0) {
+          return;
+        }
+        ;
+        if (aFields[fieldIndex] != bFields[fieldIndex]) {
+          output = aFields[fieldIndex] > bFields[fieldIndex] ? 1 : -1;
+        }
+        ;
+      });
+      return output;
+    }
+    __name(compareSemvers, "compareSemvers");
+    function findLatestSemverString(semverStringArray) {
+      let sorted = semverStringArray.sort((a, b) => compareSemvers(b, a));
+      return sorted[0];
+    }
+    __name(findLatestSemverString, "findLatestSemverString");
     exports2.dig = dig;
     exports2.bury = bury;
     exports2.fixRelationshipDataField = fixRelationshipDataField;
@@ -9108,6 +9130,8 @@ var require_schema_utilities = __commonJS({
     exports2.gitlabConventionURLTemplate = gitlabConventionURLTemplate;
     exports2.gitlabOverlayURLTemplate = gitlabOverlayURLTemplate;
     exports2.basicSchemaURLTemplate = basicSchemaURLTemplate;
+    exports2.compareSemvers = compareSemvers;
+    exports2.findLatestSemverString = findLatestSemverString;
   }
 });
 
@@ -10463,7 +10487,8 @@ var require_convention_builder = __commonJS({
       gitlabConventionURLTemplate,
       basicSchemaURLTemplate,
       arrayToStructuredConvention,
-      flattenJSONSchema
+      flattenJSONSchema,
+      findLatestSemverString
     } = require_schema_utilities();
     var papa = require_papaparse();
     function getAttributes(root, convention) {
@@ -10477,6 +10502,7 @@ var require_convention_builder = __commonJS({
       constructor({
         typeAndBundle,
         name,
+        version,
         validExamples,
         erroredExamples,
         repoURLTemplateFunction = gitlabOverlayURLTemplate,
@@ -10493,6 +10519,7 @@ var require_convention_builder = __commonJS({
         deletedAttributes = []
       }) {
         this.name = name;
+        this.version = version;
         this.typeAndBundle = typeAndBundle;
         this.validExamples = validExamples;
         this.erroredExamples = erroredExamples;
@@ -10767,14 +10794,14 @@ var require_convention_builder = __commonJS({
        */
       store(test = true) {
         this.updateSchema();
-        let targetPath = `${this.storagePath()}/${this.schemaName}`;
+        let targetPath = `${this.storagePath()}/${this.schemaName}/${this.version}/`;
         if (!this.trivial) {
           fs.mkdirSync(targetPath, { recursive: true }, console.error);
           fs.mkdirSync(`${targetPath}/examples/correct`, { recursive: true }, console.error);
           fs.mkdirSync(`${targetPath}/examples/incorrect`, { recursive: true }, console.error);
         }
         let valid = "not tested";
-        if (test) {
+        if (test && !this.trivial) {
           let test2 = this.testExamples();
           valid = test2.success;
           if (!valid) {
@@ -10995,16 +11022,21 @@ var require_convention_builder = __commonJS({
        * Adds an attribute which should be an entity represented as a schema overlay object.
        * @param {SchemaOverlay|String} schemaOverlayObject -- An object of the SchemaOverlay class or a string. If it is a string, it should be the "type--bundle" class of the desired base FarmOS schema or a preexisting overlay, using the name it's contained folder has in "collection/overlays".
        * @param {string} attributeName -- Name identifying the entity inside the schema. Typically it is not the type--bundle pair but a unique name related to its functionality inside the schema. An example would be the case in which a convention involves many quantities: you can't name each quantity "quantity", instead the logical naming pattern is alluding to what's being measured.
+       * @param {SemVer} version -- In case of string, you can indicate the version, otherwise the latest one will be used.
        * @param {boolean} required -- Indicate wether the attribute should be marked as 'required' by the schema, in which case every submission lacking this attribute will be marked as rejected.
        */
-      addAttribute({ schemaOverlayObject, attributeName, required }) {
+      addAttribute({ schemaOverlayObject, attributeName, version, required }) {
         let overlaysOnly = process.argv.includes("overlaysOnly");
         if (typeof schemaOverlayObject == "string") {
           let schemaOverlayName = schemaOverlayObject;
           let isOverlay = fs.readdirSync(`${this.storagePath()}/overlays`).find((folder) => folder == schemaOverlayObject);
           if (isOverlay) {
             try {
-              schemaOverlayObject = new SchemaOverlay2(JSON.parse(fs.readFileSync(`${this.storagePath()}/overlays/${schemaOverlayObject}/object.json`)));
+              if (!version) {
+                let versions = fs.readdirSync(`${this.storagePath()}/overlays/${schemaOverlayObject}`, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name);
+                version = findLatestSemverString(versions);
+              }
+              schemaOverlayObject = new SchemaOverlay2(JSON.parse(fs.readFileSync(`${this.storagePath()}/overlays/${schemaOverlayObject}/${version}/object.json`)));
               schemaOverlayObject.global = true;
             } catch (e) {
               if (e.code == "ENOENT" && !overlaysOnly) {
@@ -11041,6 +11073,9 @@ var require_convention_builder = __commonJS({
           schemaOverlayObject.updateSchema();
         }
         ;
+        if (!schemaOverlayObject.version) {
+          schemaOverlayObject.version = this.version;
+        }
         this.overlays[attributeName] = schemaOverlayObject;
         if (required) {
           this.required.push(attributeName);
@@ -11074,6 +11109,14 @@ var require_convention_builder = __commonJS({
         this.relationships.push({ containerEntity, relationName, mentionedEntity, required });
         this.updateSchema();
       }
+      /**
+       * Removes overlay from the convention, as well as all relationships in it or mentioning it.
+       * @param {} attributeName
+       */
+      removeOverlay(attributeName) {
+        this.relatioships = this.relationships.filter((rel) => rel.containerEntitiy != attributeName && rel.mentionedEntity != attributeName);
+        delete this.overlays[attributeName];
+      }
       /**
        * Organizes all attributes of a convention into a hierarchical binary tree, under the assumption the tree is binary.
        * @param {ConventionSchema} -- convention
@@ -11161,8 +11204,8 @@ var require_convention_builder = __commonJS({
        */
       document() {
         let header = `import CodeBlock from '@theme/CodeBlock';
-import Schema from "@site/static/schemas/${this.schemaName}/schema.json";
-import SchemaReduced from "@site/static/schemas/${this.schemaName}/schema_required_only.json";
+import Schema from "@site/static/schemas/${this.schemaName}/${this.version}/schema.json";
+import SchemaReduced from "@site/static/schemas/${this.schemaName}/${this.version}/schema_required_only.json";
 import JSONSchemaViewer from "@theme/JSONSchemaViewer";
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -11332,10 +11375,22 @@ import TabItem from '@theme/TabItem';
       getTabularRepresentation() {
         return flattenJSONSchema(this.schema, true);
       }
+      /**
+       * If no examples have been added by hand, will grab examples from the default folders in the definition's subdirectory.
+       */
+      addDefaultFolderExamples() {
+        if (!this.validExamples) {
+          this.addExample({ path: `${__dirname}/examples/correct` });
+        }
+        if (!this.erroredExamples) {
+          this.addExample({ path: `${__dirname}/examples/incorrect` });
+        }
+      }
       /**
        * Build an AJV validator and ensure all valid examples are accepted and all error examples are rejected. Returns an array attribute for each set of examples, plus a general success attribute indicating wether all examples resulted as expected and a failedExamples array only listing entities for which there was no success (meanin unrejected error examples and rejected valid examples).
        */
       testExamples() {
+        this.addDefaultFolderExamples();
         let generalOutput = {};
         if (!this.validExamples || !this.erroredExamples) {
           throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute. Valid examples amount: ${this.validExamples ? this.validExamples.length : "validExamples is not an array"}, errored examples amount: ${this.erroredExamples ? this.erroredExamples.length : "erroredExamples is not an array"}.`);
@@ -11414,10 +11469,10 @@ import TabItem from '@theme/TabItem';
           return output2;
         }
         ;
-        let targetPath = `${this.storagePath()}/conventions/${this.schemaName}`;
+        let targetPath = `${this.storagePath()}/conventions/${this.schemaName}/${this.version}`;
         let mainEntityType = this.schemaName.split("--")[0];
         let documentationFolder = `${this.storagePath()}/../documentation/Conventions/${mainEntityType}`;
-        let documentationPath = `${documentationFolder}/${this.schemaName}.mdx`;
+        let documentationPath = `${documentationFolder}/${this.schemaName}_${this.version}.mdx`;
         fs.mkdirSync(targetPath, { recursive: true }, console.error);
         fs.mkdirSync(`${targetPath}/examples/correct`, { recursive: true }, console.error);
         fs.mkdirSync(`${targetPath}/examples/incorrect`, { recursive: true }, console.error);

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "convention_builder",
-    "version": "1.8.6",
-    "description": "Helper tools that offer a high level interface that transforms a convention description into its json schema.",
+    "version": "2.0.0",
+    "description": "Helper tools that offer a high level interface that transforms a convention description into it's json schema.",
     "main": "./dist/node/index.js",
     "browser": "./dist/browser/index.js",
     "module": "./dist/module/index.js",