accordproject / cicero Goto Github PK

• Wrapper Logic syntax
• Bindings clause vars to global contract vars

Known moderate severity security vulnerability detected in marked < 0.3.7 defined in package-lock.json.package-lock.json update suggested: marked ~> 0.3.7. | Known moderate severity security vulnerability detected in marked < 0.3.7 defined in package-lock.json.package-lock.json update suggested: marked ~> 0.3.7. | Known moderate severity security vulnerability detected in marked < 0.3.7 defined in package-lock.json. | package-lock.json update suggested: marked ~> 0.3.7.

We need to update all the test templates and the cicero template library

This include changing access to data to either contract or clause (depending on use case).

Ergo needs to be updated to align with the new API. Cicero has to be switched to a new version of Ergo once alignment is achieved.

• Contract template grammar
• Contract model
• Contract logic
• package.json config
• Contract -> Clause references, import
• Child clause templates

Is there a way to indicate parameters within optional text in clauses? For instance:

In case of delayed delivery [{" except for Force Majeure cases in the 7 DAYS before the delivery date,":? forceMajeure}]

Is it be possible for the period 7 DAYS to be a parameter of the template instead of a fixed time?

In README.md the coverage badge shows a different value to the one shown on coveralls.io however the badge markdown seems to be correct

From https://coveralls.io/github/accordproject/cicero?branch=master

If we want to allow relationships to contracts and clauses, it would be useful to have contracts and clauses be asset rather than concept in the cicero-common CTO.

• Annotation in package.json to distinguish contract vs clause template
• Add unit tests

Need to think about how we represent strings in the generated grammar. At present, by default, all strings must be enclosed in double quotes, which is confusing for lawyers.

E.g. "Party A" will be deemed to in the template https://templates.accordproject.org/[email protected]

The Nearley grammar that is generated based on this template:
https://github.com/accordproject/cicero/blob/master/packages/cicero-core/lib/template.ne#L75

• READMEs
• Accord Project Template Specification
• readthedocs
• Getting started guides and tutorials (slides, etc)

Context

When running cicero parse Template.fromDirectory recursively searches the directory for model (CTO) files. This includes the node_modules directory which can contain multiple copies of some models. This results in exceptions when adding them to the model manager.

Expected Behavior

cicero cli should only load base models and explicit dependencies.

Actual Behavior

/usr/local/lib/node_modules/cicero-cli/node_modules/yargs/yargs.js:1057
      else throw err
           ^
Error: namespace already exists
    at ModelManager.addModelFiles (/usr/local/lib/node_modules/cicero-cli/node_modules/composer-common/lib/modelmanager.js:244:31)

Possible Fix

A temporary workaround is to delete the node_modules directory, rm -rf node_modules

Proper fix is to exclude node_modules unless explicitly listed as dependency
Relevant line: https://github.com/accordproject/cicero/blob/master/packages/cicero-core/lib/template.js#L709

Steps to Reproduce

1. cd accordproject/cicero-template-library/helloworld
2. npm install
3. cicero parse --template ./ --dsl ./sample.txt

Existing issues

None.

Your Environment

• Version used: cicero release 0.2.24
• Environment name and version (e.g. Chrome 39, node.js 5.4): node 8.9.3
• Operating System and version (desktop or mobile): macOS High Sierra

Now that Cicero execution returns state changes, it might be useful to allow execution of a sequence of requests for debugging purposes.

Template:

[{name}] agrees to spend [{amount}] conga coins on swag

Error:

error:  Error: unrecognized token: {"literal":""}
    at buildToken (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/node_modules/nearley/lib/compile.js:160:15)
    at buildRule (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/node_modules/nearley/lib/compile.js:95:25)
    at produceRules (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/node_modules/nearley/lib/compile.js:84:24)
    at Compile (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/node_modules/nearley/lib/compile.js:73:13)
    at Function.compileGrammar (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/node_modules/cicero-core/lib/template.js:364:39)
    at Template.setGrammar (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/node_modules/cicero-core/lib/template.js:125:36)
    at Template.buildGrammar (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/node_modules/cicero-core/lib/template.js:275:14)
    at Function.fromDirectory (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/node_modules/cicero-core/lib/template.js:787:22)
    at Function.execute (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/lib/commands.js:67:25)
    at Object.require.command.command [as handler] (/Users/sstone1/.nvm/versions/node/v8.9.0/lib/node_modules/cicero-cli/index.js:57:25)

Putting any character, including whitespace, before the variable works fine.

Also see:
#171

Currently, Jura scripts called from within Cicero are passed a deserialized request before execution. Maybe it shouldn't. Here is the corresponding code:

const code = `
        __dispatch(data,request);
        function __dispatch(data,request) {
            // Jura dispatch call
            let context = {this: data, request: serializer.toJSON(request), this: data, now: moment()};
            return serializer.fromJSON(dispatch(context));
        } 
        `;

inside the buildJuraDispatchFunction.

This may require making the Jura runtime robust to the internal representation for CTO concepts (e.g., for matching against a class or navigating relationships).

We should have consistent naming conventions in JavaScript logic to facilitate reference (and calls) between templates.

• Add Contract Model
• Add Clause Model
• Change Clause concept to be an Asset rather than a Concept so that we can use relationships
• Change 'actions' to 'emit' which should be an array of CTO events

A contract is composed of a set of clauses.

• Need some sort of data flow between the clauses
• Need a function signature for the contract
• Need a composition model for clauses and contracts, so they may be nested or reference each other
• Contract templates should stipulate required/optional clauses (implies clauses need a type)

Contract Template

• Name
• Version
• Description
• Set of required clause templates
• Set of optional clause templates

Contract

• Name
• Version
• Description
• Set of clauses
• Link to contract template

Since adding all of the cicero npm packages to the @accordproject scope, the documentation is now out of date.

For example, occurences of npm install cicero-cli -g should be replaced with npm install @accordproject/cicero-cli -g

For instance:

pursuant to and in accordance with [{{Clause XXX}}]

or

subject to [{{Clause YYY}}]

or

except for [{{Clause ZZZ}}]

Loading a template should check that the template version supports that version of Cicero.

Context

The template grammar insists that a template must have at least one parameter.
https://github.com/accordproject/cicero/blob/edd14532b80c2c4bc2a9d16a50592c3eb5733362/packages/cicero-core/lib/tdl.ne#L67

This means that clauses which only require request data, or are otherwise 'dumb' are not valid.

Expected Behavior

The following clause grammar should parse successfully:
This is a dumb clause with no template parameters

Actual Behavior

mattmbp:integration-demo-xeroviazapier matt$ cicero parse --template ./ --dsl ./sample.txt 
09:27:53 - info: Logging initialized. 2018-02-08T09:27:53.307Z
09:27:54 - error:  Error: invalid syntax at line 1 col 1:

  This clause transforms a generic payment into an invoice that will be raised in a private Xero account. The integration happens via Zapier.
  ^
Unexpected LastChunk token: "This clause transforms a generic payment into an invoice that will be raised in a private Xero account. The integration happens via Zapier.\n"

    at Parser.feed (/Users/matt/.nvm/versions/node/v8.9.3/lib/node_modules/cicero-cli/node_modules/nearley/lib/nearley.js:320:23)
    at Template.buildGrammar (/Users/matt/.nvm/versions/node/v8.9.3/lib/node_modules/cicero-cli/node_modules/cicero-core/lib/template.js:138:16)
    at template.getModelManager.updateExternalModels.then (/Users/matt/.nvm/versions/node/v8.9.3/lib/node_modules/cicero-cli/node_modules/cicero-core/lib/template.js:793:26)
    at <anonymous>

Possible Fix

Change the nearley grammar to allow zero or more items, rather than one or more.
Also be careful not to allow completely empty templates
https://github.com/accordproject/cicero/blob/edd14532b80c2c4bc2a9d16a50592c3eb5733362/packages/cicero-core/lib/tdl.ne#L67

Steps to Reproduce

Existing issues

None.

Your Environment

• Version used: cicero release 0.2.28
• Environment name and version (e.g. Chrome 39, node.js 5.4): node 8.9.3
• Operating System and version (desktop or mobile): macOS High Sierra

At the beginning of the execute statement in the cicero-engine, the serializer is called to convert from JSON with validate set to false:

    async execute(clause, request, forcejs) {
        // ensure the request is valid
        const template = clause.getTemplate();
        template.logicjsonly = forcejs;
        const tx = template.getSerializer().fromJSON(request, {validate: false, acceptResourcesForRelationships: true});
...

Should this be turned to true? What are the criteria (and consequences?) for whether to validate or not?

Ergo logic doesn't get compiled properly when loading a template from archive (rather than from disk).

Need to prove out the localization support for templates. This will require some development effort to update the Template.fromDirectory/to/fromArchive methods to support the localized template grammar files.

Context

Currently, clause logic can only specify a single return type.
e.g.
https://github.com/accordproject/cicero-template-library/blob/master/fragile-goods/lib/logic.js#L25

 * @param {io.clause.demo.fragileGoods.PayOut} context.response - the response

Expected Behavior

As a template author, I want my logic to be able to specify multiple CTO types without building a wrapper CTO type. This could be in the form of an array, or integer indexed object.

 * @param {Object[]} context.response - the response

or

 * @param {io.clause.demo.fragileGoods.PayOut} context.response.0 - the response
 * @param {io.clause.demo.fragileGoods.Message} context.response.1 - the response

Possible Fix

Need to look at this code:
https://github.com/accordproject/cicero/blob/master/packages/cicero-engine/lib/engine.js#L167

                let type${n} = '${ele.getParameterTypes()[2]}';

Existing issues

None.

There is a problem with the template name that can contains uppercase character when we want to execute it. It will show error like this:

cicero execute --template ./Kuda/ --dsl ./Kuda/sample.txt --data ./Kuda/data.json
10:16:55 - info: Logging initialized. 2018-03-18T03:16:55.730Z
/usr/local/lib/node_modules/cicero-cli/node_modules/yargs/yargs.js:1057
      else throw err
           ^

Error: template name can only contain lowercase alphanumerics, _ or -
...

But when i create the template with template generator with command:
yo cicero-template
And enter word with uppercase character there is no error
? What is the name of your template? Kuda
And my template is successfully created.

I am able to solved it by renaming manually the template name to make the uppercase character to be lowercase.
But i think it will be convenience if the generator can prevent it in the first place.

Some contract template may want to offer several choices for part of a clause. For instance:

[{" Buyer has provided": hasProvided | "Within agreed period following the full execution of this Agreement, Buyer shall provide": willProvide }] to Seller...

• Update nearley parser
• Update samples in cicero-core
• Update cicero-template-library
• Tests in other packages
• Add version check to catch legacy contracts #70

For example:

[{participant}] agrees to spend [{amount}] conga coins on [{swag}]

Because the template grammar requires a LastChunk piece of text this template parses as ambiguous (incomplete).

Need to make the LastChunk optional in the template grammar.

The generated API documentation is not handling html markup correctly:
http://accordcicero.readthedocs.io/en/latest/

This needs to be removed or converted.

It is common for templates to include multiple references to the same template model property. At the moment the first reference is used to bind to the model, all others are ignored. We should at least validate that all references are equivalent and flag an error for inconsistent bindings.

See the code here:
https://github.com/accordproject/cicero/blob/master/packages/cicero-core/lib/template.js#L304

When using cicero execute with the latest 0.2.48 release of @accordproject/cicero-cli the following error occurs.

Rather than fixing the dependency to Jura, the cicero-engine library should use the latest version of the Ergo compiler.

09:24:17 - error:  Error: ENOENT: no such file or directory, open '/Users/matt/.nvm/versions/node/v8.11.1/lib/node_modules/@accordproject/cicero-cli/node_modules/node_modules/jura-engine/lib/juraruntime.js'
    at Object.fs.openSync (fs.js:646:18)
    at Object.fs.readFileSync (fs.js:551:33)
    at Engine.execute (/Users/matt/.nvm/versions/node/v8.11.1/lib/node_modules/@accordproject/cicero-cli/node_modules/@accordproject/cicero-engine/lib/engine.js:249:31)
    at Template.fromDirectory.then (/Users/matt/.nvm/versions/node/v8.11.1/lib/node_modules/@accordproject/cicero-cli/lib/commands.js:123:31)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:188:7)
    at Function.Module.runMain (module.js:695:11)
    at startup (bootstrap_node.js:188:16)
    at bootstrap_node.js:609:3
09:24:17 - info: 

Taking an example from the latedeliveryandpenalty template, one of the sentences uses the same variable/property twice:

Any fractional part of a [{fractionalPart}] is to be considered a full
[{fractionalPart}].

The current implementation allows for distinct values of that same property, but disregards the second value. Here is a parsing run that illustrates this:

bash-3.2$ cat latedeliveryandpenalty/sample.txt  
Late Delivery and Penalty. In case of delayed delivery except for Force Majeure cases, the Seller shall pay to the Buyer for every 2 DAY of delay penalty amounting to 10.5% of the total value of the Equipment whose delivery has been delayed. Any fractional part of a DAY is to be considered a full WEEK. 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 DAY, the Buyer is entitled to terminate this Contract.
bash-3.2$ 
bash-3.2$ cicero parse --template ./latedeliveryandpenalty/ --dsl ./latedeliveryandpenalty/sample.txt  
14:58:56 - info: Logging initialized. 2017-12-23T19:58:56.569Z
14:58:56 - info: Logging initialized. 2017-12-23T19:58:56.741Z
14:58:57 - info: {"$class":"org.accordproject.latedeliveryandpenalty.TemplateModel","forceMajeure":true,"penaltyDuration":{"$class":"org.accordproject.base.Duration","amount":2,"unit":"DAY"},"penaltyPercentage":10.5,"capPercentage":55,"termination":{"$class":"org.accordproject.base.Duration","amount":15,"unit":"DAY"},"fractionalPart":"DAY"}

Note that the corresponding sentence is Any fractional part of a DAY is to be considered a full WEEK. which seems inconsistent, and the second occurrence (WEEK) of the fractional part is ignored.

Should the template parser unify on those fields used more than once, in which case the above sentence will be rejected?

The current implementation parses dates in the format MM-DD-YYYY which isn't ISO 8601 compliant. This may lead to issues when calling the moment library directly on those dates. Should Cicero allow for ISO 8601 format or automatically convert to it if required?

The corresponding part of the template processing is:

DATE -> MONTH "/" DAY "/" YEAR
{% (d) => {return '' + d[0] + '/' + d[2] + '/' + d[4]}%}

in packages/cicero-core/lib/grammarvisitor.js

The old npm packages:

• https://www.npmjs.com/package/cicero-core
• https://www.npmjs.com/package/cicero-cli
• https://www.npmjs.com/package/cicero-engine
• https://www.npmjs.com/package/cicero-server
• https://www.npmjs.com/package/generator-cicero-template

should be deprecated and a notice added that references the new packages:

• https://www.npmjs.com/package/@accordproject/cicero-core
• https://www.npmjs.com/package/@accordproject/cicero-cli
• https://www.npmjs.com/package/@accordproject/cicero-engine
• https://www.npmjs.com/package/@accordproject/cicero-server
• https://www.npmjs.com/package/@accordproject/generator-cicero-template

Use the v1.1 support for calling Node.js modules:
https://www.hyperledger.org/blog/2017/11/02/hyperledger-fabric-v1-1-0-preview-is-now-available

For instance:

Seller may terminate this Agreement:
(a) if Buyer fails to pay...
(b) if Buyer is in [{"material":?material}] breach...
(c) if Buyer becomes insolvent...

• cicero-engine
• cicero-cli
• cicero-server
• generator-cicero-template

• add state and contract data to request
• add emit side effects and state to response