feat(cicero-core): add support for Concerto vocabularies (#711)

Add locale-specific vocabulary support to Cicero templates using
Concerto's VocabularyManager. Templates can now include .voc files
in a vocab/ directory to provide localized labels for model concepts
and properties.

Changes:
- Load/save .voc files from vocab/ directory and archives
- Add VocabularyManager to Template with getVocabulary() fallback
- Add defaultLocale to Metadata (package.json accordproject section)
- Add 'cicero vocabulary' CLI command with --locale option
- Add test fixtures with English and French vocabularies
- 20 new tests covering loading, round-trip, fallback, and CLI

Closes #711

Signed-off-by: Adarsh Singh <anexus5919@gmail.com>

Author: Anexus5919

package-lock.json

@@ -160,6 +160,40 @@ require('yargs')
             return;
         }
     })
+    .command('vocabulary', 'list or query vocabulary terms for a template', (yargs) => {
+        yargs.option('template', {
+            describe: 'path to the template',
+            type: 'string'
+        });
+        yargs.option('locale', {
+            describe: 'the BCP-47 locale to query (e.g. en, fr, en-ca)',
+            type: 'string',
+            default: null
+        });
+        yargs.option('warnings', {
+            describe: 'print warnings',
+            type: 'boolean',
+            default: false
+        });
+    }, (argv) => {
+        if (argv.verbose) {
+            Logger.info(`list vocabularies for ${argv.template}`);
+        }
+
+        try {
+            argv = Commands.validateVocabularyArgs(argv);
+            const options = {
+                warnings: argv.warnings,
+            };
+            return Commands.vocabulary(argv.template, argv.locale, options)
+                .catch((err) => {
+                    Logger.error(err.message);
+                });
+        } catch (err){
+            Logger.error(err.message);
+            return;
+        }
+    })
     .command('get', 'save local copies of external dependencies', (yargs) => {
         yargs.option('template', {
             describe: 'path to the template',

packages/cicero-cli/index.js

@@ -222,6 +222,75 @@ class Commands {
         return argv;
     }
 
+    /**
+     * Set default params before we list vocabularies
+     *
+     * @param {object} argv the inbound argument values object
+     * @returns {object} a modfied argument object
+     */
+    static validateVocabularyArgs(argv) {
+        return Commands.validateCommonArgs(argv);
+    }
+
+    /**
+     * List or query vocabulary terms for a template
+     *
+     * @param {string} templatePath - path to the template directory or archive
+     * @param {string} locale - the BCP-47 locale to query
+     * @param {Object} [options] - an optional set of options
+     * @returns {object} Promise to the vocabulary information
+     */
+    static vocabulary(templatePath, locale, options) {
+        return Commands.loadTemplate(templatePath, options)
+            .then((template) => {
+                const vocManager = template.getVocabularyManager();
+                const vocFiles = template.getVocFiles();
+                const defaultLocale = template.getMetadata().getDefaultLocale();
+
+                if (vocFiles.length === 0) {
+                    Logger.info('No vocabulary files found in this template.');
+                    return {};
+                }
+
+                Logger.info(`Found ${vocFiles.length} vocabulary file(s). Default locale: ${defaultLocale || 'not set'}`);
+
+                if (locale) {
+                    // Query terms for a specific locale
+                    const modelFiles = template.getModelManager().getModelFiles().filter(mf => !mf.isSystemModelFile?.());
+                    const results = {};
+
+                    modelFiles.forEach(mf => {
+                        const ns = mf.getNamespace();
+                        const voc = template.getVocabulary(ns, locale);
+                        if (voc) {
+                            Logger.info(`\nVocabulary for ${ns} (locale: ${voc.getLocale()}):`);
+                            const terms = voc.getTerms();
+                            terms.forEach(decl => {
+                                const declName = Object.keys(decl)[0];
+                                Logger.info(`  ${declName}: ${decl[declName]}`);
+                                if (decl.properties) {
+                                    decl.properties.forEach(prop => {
+                                        const propName = Object.keys(prop)[0];
+                                        Logger.info(`    ${propName}: ${prop[propName]}`);
+                                    });
+                                }
+                            });
+                            results[ns] = terms;
+                        } else {
+                            Logger.info(`\nNo vocabulary found for ${ns} in locale: ${locale}`);
+                        }
+                    });
+                    return results;
+                } else {
+                    // List available vocabularies
+                    vocFiles.forEach(file => {
+                        Logger.info(`  - ${file.name}`);
+                    });
+                    return { files: vocFiles.map(f => f.name), defaultLocale };
+                }
+            });
+    }
+
     /**
      * Fetches all external for a set of models dependencies and
      * saves all the models to a target directory

packages/cicero-cli/lib/commands.js

@@ -269,6 +269,42 @@ describe('#get', async () => {
     });
 });
 
+describe('#validateVocabularyArgs', () => {
+    it('no args specified', () => {
+        process.chdir(path.resolve(__dirname, 'data/latedeliveryandpenalty-vocab/'));
+        const args  = Commands.validateVocabularyArgs({
+            _: ['vocabulary']
+        });
+        args.template.should.match(/cicero-cli[/\\]test[/\\]data[/\\]latedeliveryandpenalty-vocab$/);
+    });
+    it('template arg specified', () => {
+        process.chdir(path.resolve(__dirname));
+        const args  = Commands.validateVocabularyArgs({
+            _: ['vocabulary', 'data/latedeliveryandpenalty-vocab/']
+        });
+        args.template.should.match(/cicero-cli[/\\]test[/\\]data[/\\]latedeliveryandpenalty-vocab$/);
+    });
+});
+
+describe('#vocabulary', async () => {
+    it('should list vocabulary files for a template', async () => {
+        const templatePath = path.resolve(__dirname, 'data/latedeliveryandpenalty-vocab/');
+        const result = await Commands.vocabulary(templatePath, null, {});
+        result.files.length.should.equal(2);
+        result.defaultLocale.should.equal('en');
+    });
+    it('should query vocabulary terms for a specific locale', async () => {
+        const templatePath = path.resolve(__dirname, 'data/latedeliveryandpenalty-vocab/');
+        const result = await Commands.vocabulary(templatePath, 'en', {});
+        result.should.not.be.null;
+    });
+    it('should report no vocabularies for a template without vocab files', async () => {
+        const templatePath = path.resolve(__dirname, 'data/latedeliveryandpenalty/');
+        const result = await Commands.vocabulary(templatePath, null, {});
+        result.should.deep.equal({});
+    });
+});
+
 describe('#validateVerfiyArgs', () => {
     it('no args specified', () => {
         process.chdir(path.resolve(__dirname, 'data/signedArchive/'));

packages/cicero-cli/test/cli.js

@@ -0,0 +1,7 @@
+
+# Clause Template: Late Delivery And Penalty
+
+## Sample
+
+Late Delivery and Penalty. In case of delayed delivery except for Force Majeure cases, the Seller shall pay to the Buyer for every 2 days of delay penalty amounting to 10.5% of total value of the Equipment whose delivery has been delayed. Any fractional part of a day is to be considered a full day. The total amount of penalty shall not, however, exceed 55% of the total value of the Equipment involved in late delivery. If the delay is more than 15 days, the Buyer is entitled to terminate this Contract.
+

packages/cicero-cli/test/data/latedeliveryandpenalty-vocab/README.md

@@ -0,0 +1,32 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+concerto version "^3.0.0"
+
+namespace org.accordproject.contract@0.2.0
+
+/**
+ * Contract Data
+ * -- Describes the structure of contracts and clauses
+ */
+
+/* A contract is a asset -- This contains the contract data */
+abstract asset Contract identified by contractId {
+  o String contractId
+}
+
+/* A clause is an asset -- This contains the clause data */
+abstract asset Clause identified by clauseId {
+  o String clauseId
+}

packages/cicero-cli/test/data/latedeliveryandpenalty-vocab/model/@models.accordproject.org.accordproject.contract@0.2.0.cto

@@ -0,0 +1,51 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+concerto version "^3.0.0"
+
+namespace org.accordproject.runtime@0.2.0
+
+import org.accordproject.contract@0.2.0.Contract from https://models.accordproject.org/accordproject/contract@0.2.0.cto
+
+/**
+ * Runtime API
+ * -- Describes input and output of calls to a contract's clause
+ */
+
+/* A request is a transaction */
+transaction Request {
+}
+
+/* A response is a transaction */
+transaction Response {
+}
+
+/* An event that represents an obligation that needs to be fulfilled */
+abstract event Obligation identified {
+  /* A back reference to the governing contract that emitted this obligation */
+  --> Contract contract
+
+  /* The party that is obligated */
+  --> Participant promisor optional
+
+  /* The party that receives the performance */
+  --> Participant promisee optional
+
+  /* The time before which the obligation is fulfilled */
+  o DateTime deadline optional
+}
+
+/* A contract state is an asset -- The runtime state of the contract */
+asset State {
+}

packages/cicero-cli/test/data/latedeliveryandpenalty-vocab/model/@models.accordproject.org.accordproject.runtime@0.2.0.cto

@@ -0,0 +1,85 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+concerto version "^3.0.0"
+
+namespace org.accordproject.time@0.3.0
+
+/**
+ * Months of the year
+ */
+enum Month {
+  o January
+  o February
+  o March
+  o April
+  o May
+  o June
+  o July
+  o August
+  o September
+  o October
+  o November
+  o December
+}
+
+/**
+ * Days of the week
+ */
+enum Day {
+  o Monday
+  o Tuesday
+  o Wednesday
+  o Thursday
+  o Friday
+  o Saturday
+  o Sunday
+}
+
+/**
+ * Units for a duration.
+ */
+enum TemporalUnit {
+  o seconds
+  o minutes
+  o hours
+  o days
+  o weeks
+}
+
+/**
+ * A duration. For example, 6 hours.
+ */
+concept Duration {
+  o Long amount
+  o TemporalUnit unit
+}
+
+/**
+ * Units for a time period.
+ */
+enum PeriodUnit {
+  o days
+  o weeks
+  o months
+  o quarters
+  o years
+}
+
+/**
+ * A time period. For example, 2 months.
+ */
+concept Period {
+  o Long amount
+  o PeriodUnit unit
+}