Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions packages/cicero-core/src/metadata.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ export default class Metadata {

runtime: any;
ciceroVersion: any;
templateModelName: string | undefined;
logo: any;
packageJson: any;
readme: any;
Expand Down Expand Up @@ -125,6 +126,15 @@ export default class Metadata {
throw new Error('Unsupported runtime. The supported runtimes are: ' + LANGUAGES.join(', '));
}

// the fully-qualified name of the template model, when the model
// declares more than one candidate (e.g. it carries copies of the
// models of the templates it composes)
this.templateModelName = packageJson.accordproject.templateModel;

if(this.templateModelName !== undefined && (typeof this.templateModelName !== 'string' || this.templateModelName.length === 0)) {
throw new Error('The accordproject templateModel in package.json must be the fully-qualified name of a type.');
}

if(!samples || typeof(samples) !== 'object') {
throw new Error('sample.md is required');
}
Expand Down Expand Up @@ -240,6 +250,19 @@ export default class Metadata {
return this.runtime;
}

/**
* Returns the fully-qualified name of the template model, as named by
* `accordproject.templateModel` in package.json. A template only needs to
* name it when its model declares more than one concrete subtype of
* `org.accordproject.templatedata@1.0.0.TemplateData`, for example
* because it carries copies of the models of the templates it composes.
* @returns {string|undefined} the fully-qualified name of the template
* model, or undefined if package.json does not name one
*/
getTemplateModelName(){
return this.templateModelName;
}

/**
* Returns the version of Cicero that this template is compatible with.
* i.e. which version of the runtime was this template built for?
Expand Down
152 changes: 131 additions & 21 deletions packages/cicero-core/src/template.ts
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,39 @@ export default class Template {
*/
static TEMPLATE_DATA_TYPE = 'org.accordproject.templatedata@1.0.0.TemplateData';

/**
* The legacy base request type, from `org.accordproject.runtime@0.2.0`.
*
* Templates written before the 1.0 models (for example most of
* cicero-template-library) still declare their requests as subtypes of
* this. Its concrete subtypes are reported alongside those of
* {@link Template.REQUEST_TYPE}, so those templates keep working unchanged.
*/
static LEGACY_REQUEST_TYPE = 'org.accordproject.runtime@0.2.0.Request';

/**
* The legacy base response type, from `org.accordproject.runtime@0.2.0`.
* Its concrete subtypes are reported alongside those of
* {@link Template.RESPONSE_TYPE}.
*/
static LEGACY_RESPONSE_TYPE = 'org.accordproject.runtime@0.2.0.Response';

/**
* The legacy base emit type, from `org.accordproject.runtime@0.2.0`. It is
* abstract. Its concrete subtypes are reported alongside those of
* {@link Template.EMIT_TYPE}.
*/
static LEGACY_EMIT_TYPE = 'org.accordproject.runtime@0.2.0.Obligation';

/**
* The legacy base state type, from `org.accordproject.runtime@0.2.0`.
* Its concrete subtypes are reported alongside those of
* {@link Template.STATE_TYPE}. Unlike `StateData` it is a concrete (empty)
* asset, so {@link Template#isStateful} excludes it explicitly: a legacy
* template is only stateful if it declares a subtype of its own.
*/
static LEGACY_STATE_TYPE = 'org.accordproject.runtime@0.2.0.State';

metadata: any;
logicManager: any;
authorSignature: any;
Expand Down Expand Up @@ -125,21 +158,38 @@ export default class Template {
/**
* Returns the template model for the template.
*
* A template's model declares exactly one concrete subtype of
* {@link Template.TEMPLATE_DATA_TYPE}, and that subtype is the template
* model: extending `TemplateData` is the declaration, so no `@template`
* decorator is required to identify it. Templates whose model does not
* import `templatedata@1.0.0` at all - because it predates this
* convention, or because the namespace simply is not loaded - fall back
* to the legacy `@template` decorator so they keep loading unchanged.
* @throws {Error} if no template model is found, or multiple template models are found
* The template model is resolved in this order:
*
* 1. If package.json names it with `accordproject.templateModel`, that
* type. It must be a concrete subtype of
* {@link Template.TEMPLATE_DATA_TYPE}, or, for legacy templates, a
* concrete type with the `@template` decorator. A template that
* composes other templates carries copies of their models, each with
* its own subtype of `TemplateData`, so it must say which one is its
* own.
* 2. Otherwise, the model's one concrete subtype of
* {@link Template.TEMPLATE_DATA_TYPE}: extending `TemplateData` is the
* declaration, so no `@template` decorator is required to identify it.
* More than one is an error.
* 3. Otherwise - the model does not import `templatedata@1.0.0` at all,
* because it predates this convention or the namespace is simply not
* loaded - the legacy `@template` decorator, so those templates keep
* loading unchanged.
*
* @throws {Error} if no template model is found, multiple template models
* are found, or the named template model is missing or not a template model
* @returns {ClassDeclaration} the template model for the template
*/
getTemplateModel() {
const namedTemplateModel = this.getMetadata().getTemplateModelName();
if (namedTemplateModel) {
return this.getNamedTemplateModel(namedTemplateModel);
}

const templateModelNames = this.findConcreteSubclassNames(Template.TEMPLATE_DATA_TYPE);

if (templateModelNames.length > 1) {
throw new Error(`Found multiple concrete subtypes of ${Template.TEMPLATE_DATA_TYPE}: ${templateModelNames.join(', ')}. A template model must declare exactly one concrete subtype of TemplateData.`);
throw new Error(`Found multiple concrete subtypes of ${Template.TEMPLATE_DATA_TYPE}: ${templateModelNames.join(', ')}. A template model must declare exactly one concrete subtype of TemplateData, or name its template model with "accordproject.templateModel" in package.json.`);
}

if (templateModelNames.length === 1) {
Expand All @@ -149,6 +199,32 @@ export default class Template {
return templatemarkutil.findTemplateConcept(this.getIntrospector(), 'clause');
}

/**
* Returns the template model named by `accordproject.templateModel` in
* package.json, checking that it is one.
* @param {string} name the fully-qualified name of the template model
* @throws {Error} if the type is not found, or is not a concrete subtype of
* TemplateData or a concrete type with the `@template` decorator
* @returns {ClassDeclaration} the template model for the template
* @private
*/
getNamedTemplateModel(name) {
let templateModel;
try {
templateModel = this.getModelManager().getType(name);
} catch (err) {
throw new Error(`The template model "${name}" named by accordproject.templateModel in package.json was not found in the template's model: ${err.message}`);
}

const isTemplateData = Template.instanceOf(templateModel, Template.TEMPLATE_DATA_TYPE);
const isDecorated = !!templateModel.getDecorator('template');
if (templateModel.isAbstract() || (!isTemplateData && !isDecorated)) {
throw new Error(`The template model "${name}" named by accordproject.templateModel in package.json must be a concrete subtype of ${Template.TEMPLATE_DATA_TYPE}, or a concrete type with the @template decorator.`);
}

return templateModel;
}

/**
* Returns the identifier for this template
* @return {String} the identifier of this template
Expand Down Expand Up @@ -489,10 +565,11 @@ export default class Template {
* emits nothing, does not import the namespace that base type lives in.
*
* @param {String} type The fully-qualified type to search for
* @param {boolean} excludeBaseType Exclude the base parameter type, even if it is concrete
* @return {String[]} An array of fully-qualified types
* @private
*/
findConcreteSubclassNames(type) {
findConcreteSubclassNames(type, excludeBaseType = false) {
let baseType;
try {
baseType = this.getModelManager().getType(type);
Expand All @@ -505,39 +582,68 @@ export default class Template {
return baseType
.getAssignableClassDeclarations()
.filter(subclass => !subclass.isAbstract())
.filter(subclass => !excludeBaseType || subclass.getFullyQualifiedName() !== type)
.map(decl => decl.getFullyQualifiedName());
}

/**
* Returns the concrete sub-classes of each of the given base types, in the
* order the base types are given, without duplicates. Base types whose
* namespace is not loaded contribute nothing.
*
* This is how the runtime type lookups report the 1.0 models and the
* legacy `runtime@0.2.0` models side by side.
*
* @param {String[]} types The fully-qualified base types to search for
* @param {boolean} excludeBaseType Exclude each base parameter type, even if it is concrete
* @return {String[]} An array of fully-qualified types
* @private
*/
findConcreteSubclassNamesOfAny(types: string[], excludeBaseType = false): string[] {
const names: string[] = types.flatMap(type => this.findConcreteSubclassNames(type, excludeBaseType));
return Array.from(new Set(names));
}

/**
* Provides a list of the input types that are accepted by this Template. Types use the fully-qualified form.
* Includes the concrete subtypes of both {@link Template.REQUEST_TYPE} and
* the legacy {@link Template.LEGACY_REQUEST_TYPE}, 1.0 types first.
* @return {String[]} a list of the request types
*/
getRequestTypes() {
return this.findConcreteSubclassNames(Template.REQUEST_TYPE);
getRequestTypes(): string[] {
return this.findConcreteSubclassNamesOfAny([Template.REQUEST_TYPE, Template.LEGACY_REQUEST_TYPE]);
}

/**
* Provides a list of the response types that are returned by this Template. Types use the fully-qualified form.
* Includes the concrete subtypes of both {@link Template.RESPONSE_TYPE} and
* the legacy {@link Template.LEGACY_RESPONSE_TYPE}, 1.0 types first.
* @return {String[]} a list of the response types
*/
getResponseTypes() {
return this.findConcreteSubclassNames(Template.RESPONSE_TYPE);
getResponseTypes(): string[] {
return this.findConcreteSubclassNamesOfAny([Template.RESPONSE_TYPE, Template.LEGACY_RESPONSE_TYPE]);
}

/**
* Provides a list of the emit types that are emitted by this Template. Types use the fully-qualified form.
* @return {Array} a list of the emit types
* Includes the concrete subtypes of both {@link Template.EMIT_TYPE} and
* the legacy {@link Template.LEGACY_EMIT_TYPE}, 1.0 types first.
* @return {String[]} a list of the emit types
*/
getEmitTypes() {
return this.findConcreteSubclassNames(Template.EMIT_TYPE);
getEmitTypes(): string[] {
return this.findConcreteSubclassNamesOfAny([Template.EMIT_TYPE, Template.LEGACY_EMIT_TYPE]);
}

/**
* Provides a list of the state types that are expected by this Template. Types use the fully-qualified form.
* Includes the concrete subtypes of both {@link Template.STATE_TYPE} and
* the legacy {@link Template.LEGACY_STATE_TYPE}, 1.0 types first. As
* before 1.0, a legacy template's list includes the concrete base
* `runtime@0.2.0.State` itself.
* @return {String[]} a list of the state types
*/
getStateTypes() {
return this.findConcreteSubclassNames(Template.STATE_TYPE);
getStateTypes(): string[] {
return this.findConcreteSubclassNamesOfAny([Template.STATE_TYPE, Template.LEGACY_STATE_TYPE]);
}

/**
Expand All @@ -549,11 +655,15 @@ export default class Template {
}

/**
* Returns true if the template declares one or more state types.
* Returns true if the template declares one or more state types of its
* own: a concrete subtype of {@link Template.STATE_TYPE}, or of the
* legacy {@link Template.LEGACY_STATE_TYPE}. Neither base type counts:
* `StateData` is abstract, and the legacy `State` is excluded explicitly
* because it is a concrete asset.
* @return {boolean} true if the template is stateful
*/
isStateful() {
return this.getStateTypes().length > 0;
return this.findConcreteSubclassNamesOfAny([Template.STATE_TYPE, Template.LEGACY_STATE_TYPE], true).length > 0;
}

/**
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Composed Template Model

A licence template that composes a late-payment clause. It carries a copy of
the late-payment template's model, so its model declares two concrete
subtypes of `TemplateData`. `accordproject.templateModel` in package.json names
the licence's own one as the template model.
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
/*
* 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.
*/

// A reduced copy of org.accordproject.templatedata@1.0.0, carrying only the
// two extension points cicero-core resolves by name. The published namespace
// defines nothing else and imports nothing. Kept local because the namespace
// is not published yet.

concerto version "^3.0.0"

namespace org.accordproject.templatedata@1.0.0

/**
* The extension point for a template's own data model.
*
* A template's model declares exactly one concrete subtype, and that
* subtype is the template model: extending TemplateData is the
* declaration, so no `@template` decorator is required to identify it.
*/
abstract concept TemplateData {}

/**
* The extension point for template-specific runtime state.
*
* A template declares one concrete subtype and it is carried in the runtime
* state envelope: state is composed into the envelope rather than subclassing
* it, which is why this is an abstract concept and not an asset.
*/
abstract concept StateData {}
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
namespace org.accordproject.composedlatepayment@1.0.0

import org.accordproject.templatedata@1.0.0.TemplateData from https://models.accordproject.org/accordproject/templatedata@1.0.0.cto

/**
* A copy of the composed late-payment clause's template model. It is a
* concrete subtype of TemplateData too, but it is not this template's model.
*/
concept LatePaymentData extends TemplateData {
o Double penaltyPercentage
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
namespace org.accordproject.composedlicence@1.0.0

import org.accordproject.templatedata@1.0.0.TemplateData from https://models.accordproject.org/accordproject/templatedata@1.0.0.cto
import org.accordproject.composedlatepayment@1.0.0.LatePaymentData

/**
* The template model of the licence, named by accordproject.templateModel
* in package.json.
*/
concept LicenceData extends TemplateData {
o String licensee
o LatePaymentData latePayment optional
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"name": "composed-template-model",
"displayName": "Composed Template Model",
"version": "0.1.0",
"description": "A template that composes another template and so carries a copy of its model, giving two concrete subtypes of TemplateData. Used to check that accordproject.templateModel picks the template's own model.",
"author": "Accord Project",
"license": "Apache-2.0",
"accordproject": {
"template": "clause",
"cicero": "^2.0.0",
"runtime": "es6",
"templateModel": "org.accordproject.composedlicence@1.0.0.LicenceData"
},
"keywords": [
"template",
"templatedata",
"composition"
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Licensee: {{licensee}}.
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Licensee: "Acme Corp".
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Legacy Runtime Cicero 2

A template that targets cicero 2.x (`accordproject.cicero` is `^2.0.0`) but
whose model still imports `org.accordproject.runtime@0.2.0` for its request,
response, state and obligation types, as most templates in
cicero-template-library do. cicero-core reports these legacy runtime types
alongside the 1.0 ones, so the template keeps working.
Loading