Merge pull request #694 from grahampacker-ms/rename-to-architecture

issue-#693 changing terminology to architecture

.github/workflows/validate-spectral.yml

@@ -41,5 +41,5 @@ jobs:
         run: npm install @stoplight/spectral-cli
 
       - name: Run Example Spectral Linting
-        run: npx spectral lint --ruleset ./shared/dist/spectral/rules-instantiation.js 'calm/samples/api-gateway-instantiation(*.json|*.yaml)'
+        run: npx spectral lint --ruleset ./shared/dist/spectral/rules-architecture.js 'calm/samples/api-gateway-architecture(*.json|*.yaml)'
 

cli/README.md

@@ -1,7 +1,7 @@
 # CALM CLI
 
 A command line interface to interact with the CALM schema.
-You can use these tools to create an instantiation of an architectural pattern, validate that an instantiation conforms to a given pattern, and create visualizations of instantiations and patterns so that you can see what your architecture looks like.
+You can use these tools to create an architecture from a CALM pattern, validate that an architecture conforms to a given pattern, and create visualizations of architectures and patterns so that you can see what your architecture looks like.
 
 ## Using the CLI
 
@@ -27,51 +27,51 @@ Options:
 
 Commands:
   visualize [options]  Produces an SVG file representing a visualization of the CALM Specification.
-  generate [options]   Generate an instantiation from a CALM pattern file.
-  validate [options]   Validate that an instantiation conforms to a given CALM pattern.
+  generate [options]   Generate an architecture from a CALM pattern file.
+  validate [options]   Validate that an architecture conforms to a given CALM pattern.
   help [command]       display help for command
 ```
 
-### Generating an instantiation from a CALM pattern file
+### Generating an architecture from a CALM pattern file
 
-This command lets you create a shell of an instantiation from a pattern file.
+This command lets you create a shell of an architecture from a pattern file.
 You can try it out using the example patterns provided in this repo under `calm/pattern`.
 
 ```shell
 % calm generate --help
 Usage: calm generate [options]
 
-Generate an instantiation from a CALM pattern file.
+Generate an architecture from a CALM pattern file.
 
 Options:
   -p, --pattern <file>          Path to the pattern file to use. May be a file path or a URL.
-  -o, --output <file>           Path location at which to output the generated file. (default: "instantiation.json")
+  -o, --output <file>           Path location at which to output the generated file. (default: "architecture.json")
   -s, --schemaDirectory <path>  Path to the directory containing the meta schemas to use.
   -v, --verbose                 Enable verbose logging. (default: false)
-  -a, --instantiateAll          Instantiate all properties, ignoring the "required" field. (default: false)
+  -g, --generateAll             Generates all properties, ignoring the "required" field. (default: false)
   -h, --help                    display help for command
 ```
 
-The most simple way to use this command is to call it with only the pattern option, which will generate an instantiation with the default filename `instantiation.json` in the current working directory.
+The most simple way to use this command is to call it with only the pattern option, which will generate an architecture with the default filename `architecture.json` in the current working directory.
 
 ```shell
 % calm generate -p calm/pattern/api-gateway.json
 ```
 
-### Validating a CALM instantiation
+### Validating a CALM architecture
 
-This command will tell you if an instantiation matches a pattern that you provide.
+This command will tell you if an architecture matches a pattern that you provide.
 If it doesn't, then it will output a list of problems that you can address to help your architecture conform to the pattern.
 
 ```shell
 % calm validate --help
 Usage: calm validate [options]
 
-Validate that an instantiation conforms to a given CALM pattern.
+Validate that an architecture conforms to a given CALM pattern.
 
 Options:
   -p, --pattern <file>          Path to the pattern file to use. May be a file path or a URL.
-  -i, --instantiation <file>    Path to the pattern instantiation file to use. May be a file path or a URL.
+  -a, --architecture <file>     Path to the pattern architecture file to use. May be a file path or a URL.
   -s, --schemaDirectory <path>  Path to the directory containing the meta schemas to use. (default: "../calm/draft")
   --strict                      When run in strict mode, the CLI will fail if any warnings are reported. (default: false)
   -f, --format <format>         The format of the output (choices: "json", "junit", default: "json")
@@ -82,13 +82,13 @@ Options:
 
 
 This command can output warnings and errors - the command will only exit with an error code if there are errors present in the output.
-Warnings are sometimes provided as hints about how to improve the instantiation, but they are not essential for the architecture to match the pattern.
+Warnings are sometimes provided as hints about how to improve the architecture, but they are not essential for the architecture to match the pattern.
 
-If you were to try and generate an instantiation from the api-pattern, and then validate the instantation against that pattern like this
+If you were to try and generate an architecture from the api-pattern, and then validate the architecture against that pattern like this
 
 ```shell
 % calm generate -p calm/pattern/api-gateway.json
-% calm validate -p calm/pattern/api-gateway.json -i instantiation.json
+% calm validate -p calm/pattern/api-gateway.json -a architecture.json
 ```
 
 You would get an output which includes a warning like this:
@@ -99,9 +99,9 @@ You would get an output which includes a warning like this:
     "jsonSchemaValidationOutputs": [],
     "spectralSchemaValidationOutputs": [
         {
-            "code": "instantiation-has-no-placeholder-properties-string",
+            "code": "architecture-has-no-placeholder-properties-string",
             "severity": "warning",
-            "message": "String placeholder detected in instantiated pattern.",
+            "message": "String placeholder detected in architecture.",
             "path": "/nodes/0/interfaces/0/host",
             "schemaPath": "",
             "line_start": 10,
@@ -110,9 +110,9 @@ You would get an output which includes a warning like this:
             "character_end": 30
         },
         {
-            "code": "instantiation-has-no-placeholder-properties-numerical",
+            "code": "architecture-has-no-placeholder-properties-numerical",
             "severity": "warning",
-            "message": "Numerical placeholder (-1) detected in instantiated pattern.",
+            "message": "Numerical placeholder (-1) detected in architecture.",
             "path": "/nodes/0/interfaces/0/port",
             "schemaPath": "",
             "line_start": 11,
@@ -121,9 +121,9 @@ You would get an output which includes a warning like this:
             "character_end": 20
         },
         {
-            "code": "instantiation-has-no-placeholder-properties-string",
+            "code": "architecture-has-no-placeholder-properties-string",
             "severity": "warning",
-            "message": "String placeholder detected in instantiated pattern.",
+            "message": "String placeholder detected in architecture.",
             "path": "/nodes/0/well-known-endpoint",
             "schemaPath": "",
             "line_start": 14,
@@ -132,9 +132,9 @@ You would get an output which includes a warning like this:
             "character_end": 56
         },
         {
-            "code": "instantiation-has-no-placeholder-properties-string",
+            "code": "architecture-has-no-placeholder-properties-string",
             "severity": "warning",
-            "message": "String placeholder detected in instantiated pattern.",
+            "message": "String placeholder detected in architecture.",
             "path": "/nodes/2/interfaces/0/host",
             "schemaPath": "",
             "line_start": 31,
@@ -143,9 +143,9 @@ You would get an output which includes a warning like this:
             "character_end": 30
         },
         {
-            "code": "instantiation-has-no-placeholder-properties-numerical",
+            "code": "architecture-has-no-placeholder-properties-numerical",
             "severity": "warning",
-            "message": "Numerical placeholder (-1) detected in instantiated pattern.",
+            "message": "Numerical placeholder (-1) detected in architecture.",
             "path": "/nodes/2/interfaces/0/port",
             "schemaPath": "",
             "line_start": 32,
@@ -166,7 +166,7 @@ This isn't a full break, but it implies that you've forgotten to fill out a deta
 ### Visualizing the CALM schema
 
 In order to take a look at the architecture that you're working on, beyond just staring at a json file, you can use the visualize command.
-This command accepts either an instantiation or a pattern as it's input (not both), and will output an SVG file.
+This command accepts either an architecture or a pattern as it's input (not both), and will output an SVG file.
 You can then open up that file in the browser to see a box and line diagram which represents your architecture.
 
 ```shell
@@ -176,7 +176,7 @@ Usage: calm visualize [options]
 Produces an SVG file representing a visualization of the CALM Specification.
 
 Options:
-  -i, --instantiation <file>  Path to an instantiation of a CALM pattern.
+  -a, --architecture <file>   Path to an architecture of a CALM pattern.
   -p, --pattern <file>        Path to a CALM pattern.
   -o, --output <file>         Path location at which to output the SVG. (default: "calm-visualization.svg")
   -v, --verbose               Enable verbose logging. (default: false)

cli/src/cli.spec.ts

@@ -55,7 +55,7 @@ describe('CLI Integration Tests', () => {
     });
 
     test('example validate command - outputting JSON to stdout', (done) => {
-        const exampleValidateCommand = 'calm validate -p ../calm/pattern/api-gateway.json -i ../calm/samples/api-gateway-instantiation.json';
+        const exampleValidateCommand = 'calm validate -p ../calm/pattern/api-gateway.json -a ../calm/samples/api-gateway-architecture.json';
         exec(exampleValidateCommand, (_error, stdout, _stderr) => {
             const parsedOutput = JSON.parse(stdout);
             const expectedFilePath = path.join(__dirname, '../test_fixtures/validate_output.json');
@@ -67,7 +67,7 @@ describe('CLI Integration Tests', () => {
 
     test('example validate command - outputting JSON to file', (done) => {
         const targetOutputFile = path.join(tempDir, 'validate-output.json');
-        const exampleValidateCommand = `calm validate -p ../calm/pattern/api-gateway.json -i ../calm/samples/api-gateway-instantiation.json -o ${targetOutputFile}`;
+        const exampleValidateCommand = `calm validate -p ../calm/pattern/api-gateway.json -a ../calm/samples/api-gateway-architecture.json -o ${targetOutputFile}`;
         exec(exampleValidateCommand, (_error, _stdout, _stderr) => {
             expect(fs.existsSync(targetOutputFile)).toBeTruthy();
 
@@ -84,7 +84,7 @@ describe('CLI Integration Tests', () => {
     });
 
     test('example validate command - outputting JUNIT to stdout', (done) => {
-        const exampleValidateCommand = 'calm validate -p ../calm/pattern/api-gateway.json -i ../calm/samples/api-gateway-instantiation.json -f junit';
+        const exampleValidateCommand = 'calm validate -p ../calm/pattern/api-gateway.json -a ../calm/samples/api-gateway-architecture.json -f junit';
         exec(exampleValidateCommand, async (_error, stdout, _stderr) => {
             const parsedOutput = await parseStringPromise(stdout);
 
@@ -99,7 +99,7 @@ describe('CLI Integration Tests', () => {
 
     test('example validate command - outputting JUNIT to file', (done) => {
         const targetOutputFile = path.join(tempDir, 'validate-output.xml');
-        const exampleValidateCommand = `calm validate -p ../calm/pattern/api-gateway.json -i ../calm/samples/api-gateway-instantiation.json -f junit -o ${targetOutputFile}`;
+        const exampleValidateCommand = `calm validate -p ../calm/pattern/api-gateway.json -a ../calm/samples/api-gateway-architecture.json -f junit -o ${targetOutputFile}`;
         exec(exampleValidateCommand, async (_error, _stdout, _stderr) => {
             expect(fs.existsSync(targetOutputFile)).toBeTruthy();
 
@@ -136,7 +136,7 @@ describe('CLI Integration Tests', () => {
     });
 
     test('example validate command - outputting PRETTY to stdout', (done) => {
-        const exampleValidateCommand = 'calm validate -p ../calm/pattern/api-gateway.json -i ../calm/samples/api-gateway-instantiation.json -f pretty';
+        const exampleValidateCommand = 'calm validate -p ../calm/pattern/api-gateway.json -a ../calm/samples/api-gateway-architecture.json -f pretty';
         exec(exampleValidateCommand, (_error, stdout, _stderr) => {
             const expectedFilePath = path.join(__dirname, '../test_fixtures/validate_output_pretty.txt');
             const expectedOutput = fs.readFileSync(expectedFilePath, 'utf-8');
@@ -148,7 +148,7 @@ describe('CLI Integration Tests', () => {
 
     test('example validate command - outputting PRETTY to file', (done) => {
         const targetOutputFile = path.join(tempDir, 'validate-output-pretty.txt');
-        const exampleValidateCommand = `calm validate -p ../calm/pattern/api-gateway.json -i ../calm/samples/api-gateway-instantiation.json -f pretty -o ${targetOutputFile}`;
+        const exampleValidateCommand = `calm validate -p ../calm/pattern/api-gateway.json -a ../calm/samples/api-gateway-architecture.json -f pretty -o ${targetOutputFile}`;
         exec(exampleValidateCommand, (_error, _stdout, _stderr) => {
             expect(fs.existsSync(targetOutputFile)).toBeTruthy();
 

cli/src/index.ts

@@ -1,14 +1,14 @@
 #! /usr/bin/env node
 
-import { CALM_META_SCHEMA_DIRECTORY, getFormattedOutput, runGenerate, validate, visualizeInstantiation, visualizePattern, exitBasedOffOfValidationOutcome } from '@finos/calm-shared';
+import { CALM_META_SCHEMA_DIRECTORY, getFormattedOutput, runGenerate, validate, visualizeArchitecture, visualizePattern, exitBasedOffOfValidationOutcome } from '@finos/calm-shared';
 import { Option, program } from 'commander';
 import path from 'path';
 import { mkdirp } from 'mkdirp';
 import { writeFileSync } from 'fs';
 
 const FORMAT_OPTION = '-f, --format <format>';
-const INSTANTIATION_OPTION = '-i, --instantiation <file>';
-const INSTANTIATE_ALL_OPTION = '-a, --instantiateAll';
+const ARCHITECTURE_OPTION = '-a, --architecture <file>';
+const GENERATE_ALL_OPTION = '-g, --generateAll';
 const OUTPUT_OPTION = '-o, --output <file>';
 const PATTERN_OPTION = '-p, --pattern <file>';
 const SCHEMAS_OPTION = '-s, --schemaDirectory <path>';
@@ -23,37 +23,37 @@ program
 program
     .command('visualize')
     .description('Produces an SVG file representing a visualization of the CALM Specification.')
-    .addOption(new Option(INSTANTIATION_OPTION, 'Path to an instantiation of a CALM pattern.').conflicts('pattern'))
-    .addOption(new Option(PATTERN_OPTION, 'Path to a CALM pattern.').conflicts('instantiation'))
+    .addOption(new Option(ARCHITECTURE_OPTION, 'Path to an architecture of a CALM pattern.').conflicts('pattern'))
+    .addOption(new Option(PATTERN_OPTION, 'Path to a CALM pattern.').conflicts('architecture'))
     .requiredOption(OUTPUT_OPTION, 'Path location at which to output the SVG.', 'calm-visualization.svg')
     .option(VERBOSE_OPTION, 'Enable verbose logging.', false)
     .action(async (options) => {
-        if (options.instantiation) {
-            await visualizeInstantiation(options.instantiation, options.output, !!options.verbose);
+        if (options.architecture) {
+            await visualizeArchitecture(options.architecture, options.output, !!options.verbose);
         } else if (options.pattern) {
             await visualizePattern(options.pattern, options.output, !!options.verbose);
         } else {
-            program.error(`error: one of required options '${INSTANTIATION_OPTION}' or '${PATTERN_OPTION}' not specified`);
+            program.error(`error: one of required options '${ARCHITECTURE_OPTION}' or '${PATTERN_OPTION}' not specified`);
         }
     });
 
 program
     .command('generate')
-    .description('Generate an instantiation from a CALM pattern file.')
+    .description('Generate an architecture from a CALM pattern file.')
     .requiredOption(PATTERN_OPTION, 'Path to the pattern file to use. May be a file path or a URL.')
-    .requiredOption(OUTPUT_OPTION, 'Path location at which to output the generated file.', 'instantiation.json')
+    .requiredOption(OUTPUT_OPTION, 'Path location at which to output the generated file.', 'architecture.json')
     .option(SCHEMAS_OPTION, 'Path to the directory containing the meta schemas to use.')
     .option(VERBOSE_OPTION, 'Enable verbose logging.', false)
-    .option(INSTANTIATE_ALL_OPTION, 'Instantiate all properties, ignoring the "required" field.', false)
+    .option(GENERATE_ALL_OPTION, 'Generate all properties, ignoring the "required" field.', false)
     .action(async (options) =>
-        await runGenerate(options.pattern, options.output, !!options.verbose, options.instantiateAll, options.schemaDirectory)
+        await runGenerate(options.pattern, options.output, !!options.verbose, options.generateAll, options.schemaDirectory)
     );
 
 program
     .command('validate')
-    .description('Validate that an instantiation conforms to a given CALM pattern.')
+    .description('Validate that an architecture conforms to a given CALM pattern.')
     .requiredOption(PATTERN_OPTION, 'Path to the pattern file to use. May be a file path or a URL.')
-    .option(INSTANTIATION_OPTION, 'Path to the pattern instantiation file to use. May be a file path or a URL.')
+    .option(ARCHITECTURE_OPTION, 'Path to the architecture file to use. May be a file path or a URL.')
     .option(SCHEMAS_OPTION, 'Path to the directory containing the meta schemas to use.', CALM_META_SCHEMA_DIRECTORY)
     .option(STRICT_OPTION, 'When run in strict mode, the CLI will fail if any warnings are reported.', false)
     .addOption(
@@ -64,7 +64,7 @@ program
     .option(OUTPUT_OPTION, 'Path location at which to output the generated file.')
     .option(VERBOSE_OPTION, 'Enable verbose logging.', false)
     .action(async (options) => {
-        const outcome = await validate(options.instantiation, options.pattern, options.schemaDirectory, options.verbose);
+        const outcome = await validate(options.architecture, options.pattern, options.schemaDirectory, options.verbose);
         const content = getFormattedOutput(outcome, options.format);
         writeOutputFile(options.output, content);
         exitBasedOffOfValidationOutcome(outcome, options.strict);

cli/test_fixtures/validate_output.json

@@ -2,9 +2,9 @@
         "jsonSchemaValidationOutputs": [],
         "spectralSchemaValidationOutputs": [
             {
-                "code": "instantiation-has-no-placeholder-properties-numerical",
+                "code": "architecture-has-no-placeholder-properties-numerical",
                 "severity": "warning",
-                "message": "Numerical placeholder (-1) detected in instantiated pattern.",
+                "message": "Numerical placeholder (-1) detected in architecture.",
                 "path": "/nodes/2/interfaces/0/port",
                 "schemaPath": "",
                 "line_start": 32,