From 92b91168cc09bb0923c45003f3f3ba870c5dec63 Mon Sep 17 00:00:00 2001 From: Graham Packer Date: Thu, 19 Dec 2024 18:07:29 +0000 Subject: [PATCH] issue-#693 changing terminology to architecture --- .github/workflows/validate-spectral.yml | 2 +- ...ion.json => api-gateway-architecture.json} | 0 cli/README.md | 56 +++++++++---------- cli/src/cli.spec.ts | 12 ++-- cli/src/index.ts | 30 +++++----- cli/test_fixtures/validate_output.json | 4 +- cli/test_fixtures/validate_output_junit.xml | 22 ++++---- cli/test_fixtures/validate_output_pretty.txt | 6 +- docs/docs/introduction/key-features.md | 4 +- docs/docs/introduction/what-is-calm.md | 2 +- docs/docs/introduction/why-use-calm.md | 2 +- docs/docs/working-with-calm/generate.md | 16 +++--- docs/docs/working-with-calm/index.md | 2 +- docs/docs/working-with-calm/using-the-cli.md | 4 +- docs/docs/working-with-calm/validate.md | 14 ++--- docs/docs/working-with-calm/visualize.md | 6 +- shared/README.md | 2 +- shared/src/commands/generate/generate.spec.ts | 2 +- shared/src/commands/generate/generate.ts | 4 +- shared/src/commands/generate/util.ts | 6 +- .../output-formats/junit-output.spec.ts | 2 +- shared/src/commands/validate/validate.spec.ts | 28 +++++----- shared/src/commands/validate/validate.ts | 40 ++++++------- .../src/commands/visualize/calmToDot.spec.ts | 4 +- shared/src/commands/visualize/calmToDot.ts | 4 +- .../src/commands/visualize/visualize.spec.ts | 12 ++-- shared/src/commands/visualize/visualize.ts | 16 +++--- shared/src/index.ts | 2 +- .../ids-are-unique.ts | 0 .../interface-id-exists.ts | 0 .../node-has-relationship.ts | 0 .../node-id-exists.ts | 0 .../spectral/pattern/validation-rules.yaml | 4 +- ...instantiation.ts => rules-architecture.ts} | 40 ++++++------- shared/src/spectral/rules-pattern.ts | 4 +- shared/src/types.ts | 2 +- 36 files changed, 177 insertions(+), 177 deletions(-) rename calm/samples/{api-gateway-instantiation.json => api-gateway-architecture.json} (100%) rename shared/src/spectral/functions/{instantiation => architecture}/ids-are-unique.ts (100%) rename shared/src/spectral/functions/{instantiation => architecture}/interface-id-exists.ts (100%) rename shared/src/spectral/functions/{instantiation => architecture}/node-has-relationship.ts (100%) rename shared/src/spectral/functions/{instantiation => architecture}/node-id-exists.ts (100%) rename shared/src/spectral/{rules-instantiation.ts => rules-architecture.ts} (74%) diff --git a/.github/workflows/validate-spectral.yml b/.github/workflows/validate-spectral.yml index 5f22e245..49255e62 100644 --- a/.github/workflows/validate-spectral.yml +++ b/.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)' diff --git a/calm/samples/api-gateway-instantiation.json b/calm/samples/api-gateway-architecture.json similarity index 100% rename from calm/samples/api-gateway-instantiation.json rename to calm/samples/api-gateway-architecture.json diff --git a/cli/README.md b/cli/README.md index 88861188..6cc5f9d1 100644 --- a/cli/README.md +++ b/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 Path to the pattern file to use. May be a file path or a URL. - -o, --output Path location at which to output the generated file. (default: "instantiation.json") + -o, --output Path location at which to output the generated file. (default: "architecture.json") -s, --schemaDirectory 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 Path to the pattern file to use. May be a file path or a URL. - -i, --instantiation Path to the pattern instantiation file to use. May be a file path or a URL. + -a, --architecture Path to the pattern architecture file to use. May be a file path or a URL. -s, --schemaDirectory 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 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 Path to an instantiation of a CALM pattern. + -a, --architecture Path to an architecture of a CALM pattern. -p, --pattern Path to a CALM pattern. -o, --output Path location at which to output the SVG. (default: "calm-visualization.svg") -v, --verbose Enable verbose logging. (default: false) diff --git a/cli/src/cli.spec.ts b/cli/src/cli.spec.ts index d0a75ac3..37949c61 100644 --- a/cli/src/cli.spec.ts +++ b/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(); diff --git a/cli/src/index.ts b/cli/src/index.ts index fcbb2115..60fe59a7 100644 --- a/cli/src/index.ts +++ b/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 '; -const INSTANTIATION_OPTION = '-i, --instantiation '; -const INSTANTIATE_ALL_OPTION = '-a, --instantiateAll'; +const ARCHITECTURE_OPTION = '-a, --architecture '; +const GENERATE_ALL_OPTION = '-g, --generateAll'; const OUTPUT_OPTION = '-o, --output '; const PATTERN_OPTION = '-p, --pattern '; const SCHEMAS_OPTION = '-s, --schemaDirectory '; @@ -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); diff --git a/cli/test_fixtures/validate_output.json b/cli/test_fixtures/validate_output.json index c3d07a77..8eb4839e 100644 --- a/cli/test_fixtures/validate_output.json +++ b/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, diff --git a/cli/test_fixtures/validate_output_junit.xml b/cli/test_fixtures/validate_output_junit.xml index cc2ef80e..52b86f9f 100644 --- a/cli/test_fixtures/validate_output_junit.xml +++ b/cli/test_fixtures/validate_output_junit.xml @@ -6,20 +6,20 @@ - - + + - - - + name="architecture-has-no-placeholder-properties-numerical" /> + + + - - - + name="connects-relationship-references-existing-nodes-in-architecture" /> + + + + name="unique-ids-must-be-unique-in-architecture" /> diff --git a/cli/test_fixtures/validate_output_pretty.txt b/cli/test_fixtures/validate_output_pretty.txt index 7021f5ab..ebeb1e38 100644 --- a/cli/test_fixtures/validate_output_pretty.txt +++ b/cli/test_fixtures/validate_output_pretty.txt @@ -7,6 +7,6 @@ Warnings: -| code | severity | message | path | schemaPath | line_start | line_end | character_start | character_end | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -| instantiation-has-no-placeholder-properties-numerical | warning | Numerical placeholder (-1) detected in instantiated pattern. | /nodes/2/interfaces/0/port | | 32 | 32 | 18 | 20 | +| code | severity | message | path | schemaPath | line_start | line_end | character_start | character_end | +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +| architecture-has-no-placeholder-properties-numerical | warning | Numerical placeholder (-1) detected in architecture. | /nodes/2/interfaces/0/port | | 32 | 32 | 18 | 20 | diff --git a/docs/docs/introduction/key-features.md b/docs/docs/introduction/key-features.md index 85a3b9c1..743d7135 100644 --- a/docs/docs/introduction/key-features.md +++ b/docs/docs/introduction/key-features.md @@ -19,7 +19,7 @@ At the heart of CALM is its JSON Meta Schema, which provides a standardized form One of the most powerful aspects of CALM is its ability to validate architectures against predefined patterns. This ensures that designs adhere to best practices and organizational standards. -- **Pattern-Based Validation**: Use CALM’s CLI to validate instantiations against approved patterns, catching errors early in the design phase. +- **Pattern-Based Validation**: Use CALM’s CLI to validate architectures against approved patterns, catching errors early in the design phase. - **Automated Compliance Checks**: Integrate CALM validation into your CI/CD pipeline to enforce compliance automatically, reducing the burden of manual reviews. ## 3. Visualization @@ -31,7 +31,7 @@ Understanding complex architectures can be challenging, especially when dealing ## 4. Patterns and Reuse -CALM supports the creation and reuse of architectural patterns, allowing you to encapsulate common designs and quickly instantiate them for specific use cases. +CALM supports the creation and reuse of architectural patterns, allowing you to encapsulate common designs and quickly generate them for specific use cases. - **Reusable Components**: Define patterns for common architectural structures, such as microservices, API gateways, or data pipelines. - **Pre-Approved Designs**: Use pre-approved patterns to speed up development, reduce review times, and ensure consistency across projects. diff --git a/docs/docs/introduction/what-is-calm.md b/docs/docs/introduction/what-is-calm.md index 2a63af4c..0d024787 100644 --- a/docs/docs/introduction/what-is-calm.md +++ b/docs/docs/introduction/what-is-calm.md @@ -65,6 +65,6 @@ To start using CALM, you can install the CALM CLI and begin exploring its capabi ```shell npm install -g @finos/calm-cli ``` -2. **Explore the CLI Commands**: Use the CLI to generate, validate, and visualize architectural patterns and instantiations. +2. **Explore the CLI Commands**: Use the CLI to generate, validate, and visualize architectural patterns and architectures. 3. **Join the Community**: Contribute to the CALM monorepo, engage with other architects, and help evolve the standard. diff --git a/docs/docs/introduction/why-use-calm.md b/docs/docs/introduction/why-use-calm.md index d4fd8a95..6998da9b 100644 --- a/docs/docs/introduction/why-use-calm.md +++ b/docs/docs/introduction/why-use-calm.md @@ -39,7 +39,7 @@ By defining architecture as code, CALM allows you to manage your architectural d One of CALM’s key strengths is its ability to automate the validation of architectural designs against predefined patterns. This helps ensure that your system adheres to best practices and organizational standards: -- **Pattern-Based Validation**: Use CALM CLI to validate architectural instantiations, catching issues early in the design phase. +- **Pattern-Based Validation**: Use CALM CLI to validate architectural architectures, catching issues early in the design phase. - **CI/CD Integration**: Incorporate architectural validation into your CI/CD pipelines, automatically checking compliance and preventing deviations from approved designs. ### 4. **Visualization and Communication** diff --git a/docs/docs/working-with-calm/generate.md b/docs/docs/working-with-calm/generate.md index 666b0ae2..9c3f244c 100644 --- a/docs/docs/working-with-calm/generate.md +++ b/docs/docs/working-with-calm/generate.md @@ -6,28 +6,28 @@ sidebar_position: 4 # Generate -The `generate` command allows you to create an instantiation of an architecture from a predefined CALM pattern. This command helps you quickly set up the structure of your architecture using reusable patterns, which can then be customized to fit your specific needs. +The `generate` command allows you to create an architecture of an architecture from a predefined CALM pattern. This command helps you quickly set up the structure of your architecture using reusable patterns, which can then be customized to fit your specific needs. ## Basic Usage -To generate an instantiation, you will need a pattern file that defines the architecture template. You can use the `generate` command with the `--pattern` option to specify the path to the pattern file: +To generate an architecture, you will need a pattern file that defines the architecture template. You can use the `generate` command with the `--pattern` option to specify the path to the pattern file: ```shell calm generate -p calm/pattern/api-gateway.json ``` -This will create an instantiation in the current working directory with the default filename `instantiation.json`. +This will create an architecture in the current working directory with the default filename `architecture.json`. ## Command Options - **`-p, --pattern `**: Path to the pattern file to use. This can be a file path or a URL. -- **`-o, --output `**: Path to the location where the generated file will be saved (default is `instantiation.json`). -- **`-s, --schemaDirectory `**: Path to the directory containing schemas to use in instantiation. -- **`-a, --instantiateAll`**: Instantiate all properties, ignoring the "required" field (default: false). +- **`-o, --output `**: Path to the location where the generated file will be saved (default is `architecture.json`). +- **`-s, --schemaDirectory `**: Path to the directory containing schemas to use in architecture. +- **`-g, --generateAll`**: Generates all properties, ignoring the "required" field (default: false). -## Example of Generating an Instantiation +## Example of Generating an architecture -Here is an example command that generates an instantiation from a CALM pattern file and saves it with a custom filename: +Here is an example command that generates an architecture from a CALM pattern file and saves it with a custom filename: ```shell calm generate -p calm/pattern/microservices.json -o my-architecture.json diff --git a/docs/docs/working-with-calm/index.md b/docs/docs/working-with-calm/index.md index 8351a602..9fb7e4d3 100644 --- a/docs/docs/working-with-calm/index.md +++ b/docs/docs/working-with-calm/index.md @@ -12,7 +12,7 @@ Explore the topics below to get hands-on experience with CALM: - [Installation](installation): Learn how to set up the CALM CLI on your machine. - [Using the CLI](using-the-cli): Understand the basic usage of the CALM CLI and how to access its commands. -- [Generate](generate): Discover how to generate architectural instantiations from predefined patterns. +- [Generate](generate): Discover how to generate architectural architectures from predefined patterns. - [Validate](validate): Learn how to validate your architecture against CALM patterns to ensure compliance. - [Visualize](visualize): See how to create visual representations of your architecture directly from CALM definitions. diff --git a/docs/docs/working-with-calm/using-the-cli.md b/docs/docs/working-with-calm/using-the-cli.md index 7f337266..47dec003 100644 --- a/docs/docs/working-with-calm/using-the-cli.md +++ b/docs/docs/working-with-calm/using-the-cli.md @@ -27,8 +27,8 @@ Options: -V, --version output the version number -h, --help display help for com 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 ``` \ No newline at end of file diff --git a/docs/docs/working-with-calm/validate.md b/docs/docs/working-with-calm/validate.md index f4a3f83f..36d3d3ee 100644 --- a/docs/docs/working-with-calm/validate.md +++ b/docs/docs/working-with-calm/validate.md @@ -6,31 +6,31 @@ sidebar_position: 5 # Validate -The `validate` command is used to check if an instantiation conforms to a given CALM pattern. Validation helps ensure that your architecture adheres to best practices and meets the required standards. +The `validate` command is used to check if an architecture conforms to a given CALM pattern. Validation helps ensure that your architecture adheres to best practices and meets the required standards. ## Basic Usage -To validate an instantiation against a pattern, use the `validate` command with the `--pattern` and `--instantiation` options: +To validate an architecture against a pattern, use the `validate` command with the `--pattern` and `--architecture` options: ```shell -calm validate -p calm/pattern/api-pattern.json -i instantiation.json +calm validate -p calm/pattern/api-pattern.json -a architecture.json ``` -If the instantiation does not match the pattern, the command will output a list of errors and warnings that need to be addressed. +If the architecture does not match the pattern, the command will output a list of errors and warnings that need to be addressed. ## Command Options - **`-p, --pattern `**: Path to the pattern file. This can be a local file path or a URL. -- **`-i, --instantiation `**: Path to the instantiation file to validate. +- **`-a, --architecture `**: Path to the architecture file to validate. - **`-f, --format `**: The format of the output (choices: "json", "junit", default: "json"). - **`-v, --verbose`**: Enable verbose logging to see detailed validation output. ## Example of Validation -Here is an example command that validates an instantiation against a pattern and outputs the results in JSON format: +Here is an example command that validates an architecture against a pattern and outputs the results in JSON format: ```shell -calm validate -p calm/pattern/api-pattern.json -i my-architecture.json -f json +calm validate -p calm/pattern/api-pattern.json -a my-architecture.json -f json ``` This command will check if `my-architecture.json` conforms to the `api-pattern.json` and display any validation errors or warnings. diff --git a/docs/docs/working-with-calm/visualize.md b/docs/docs/working-with-calm/visualize.md index e2a447e2..b9cc39eb 100644 --- a/docs/docs/working-with-calm/visualize.md +++ b/docs/docs/working-with-calm/visualize.md @@ -10,17 +10,17 @@ The `visualize` command allows you to create visual representations of your arch ## Basic Usage -To visualize an instantiation or a pattern, use the `visualize` command with either the `--instantiation` or `--pattern` option: +To visualize an architecture or a pattern, use the `visualize` command with either the `--architecture` or `--pattern` option: ```shell -calm visualize -i instantiation.json +calm visualize -a architecture.json ``` This command generates an SVG file (`calm-visualization.svg` by default) that you can open in a browser or other image viewer. ## Command Options -- **`-i, --instantiation `**: Path to an instantiation file of a CALM pattern. +- **`-a, --architecture `**: Path to an architecture file of a CALM pattern. - **`-p, --pattern `**: Path to a CALM pattern file. - **`-o, --output `**: Path where the SVG file will be saved (default: `calm-visualization.svg`). - **`-v, --verbose`**: Enable verbose logging to see detailed output. diff --git a/shared/README.md b/shared/README.md index 06c47272..8b378655 100644 --- a/shared/README.md +++ b/shared/README.md @@ -35,7 +35,7 @@ npm install npm run build # 3 Invoke spectral referencing the disted rules you're interested in -spectral lint --ruleset ./shared/dist/spectral/rules-instantiation.js ./shared/spectral-examples/bad-rest-api.json +spectral lint --ruleset ./shared/dist/spectral/rules-architecture.js ./shared/spectral-examples/bad-rest-api.json ``` ## Learn more diff --git a/shared/src/commands/generate/generate.spec.ts b/shared/src/commands/generate/generate.spec.ts index d2f9f9f7..0a0048b9 100644 --- a/shared/src/commands/generate/generate.spec.ts +++ b/shared/src/commands/generate/generate.spec.ts @@ -49,7 +49,7 @@ describe('runGenerate', () => { .toBeTruthy(); }); - it('instantiates to calm instantiation file', async () => { + it('instantiates to calm architecture file', async () => { const outPath = path.join(tempDirectoryPath, 'output.json'); await runGenerate(testPath, outPath, false, false); diff --git a/shared/src/commands/generate/generate.ts b/shared/src/commands/generate/generate.ts index 9ee38844..a0ebaff5 100644 --- a/shared/src/commands/generate/generate.ts +++ b/shared/src/commands/generate/generate.ts @@ -4,7 +4,7 @@ import {mkdirp} from 'mkdirp'; import * as winston from 'winston'; import {initLogger} from '../helper.js'; -import {CALMInstantiation} from '../../types.js'; +import {CALMArchitecture} from '../../types.js'; import {SchemaDirectory} from './schema-directory.js'; import {instantiateNodes} from './components/node.js'; import {instantiateRelationships} from './components/relationship.js'; @@ -34,7 +34,7 @@ function loadFile(path: string): object { } -export async function generate(patternPath: string, debug: boolean, instantiateAll: boolean, schemaDirectoryPath?: string): Promise { +export async function generate(patternPath: string, debug: boolean, instantiateAll: boolean, schemaDirectoryPath?: string): Promise { logger = initLogger(debug); const schemaDirectory = new SchemaDirectory(debug); diff --git a/shared/src/commands/generate/util.ts b/shared/src/commands/generate/util.ts index 75d6a4a7..fbfbaadc 100644 --- a/shared/src/commands/generate/util.ts +++ b/shared/src/commands/generate/util.ts @@ -19,9 +19,9 @@ export function mergeSchemas(s1: object, s2: object) { return newSchema; } -export function logRequiredMessage(logger: Logger, required: string[], instantiateAll: boolean) { - if (instantiateAll) { - logger.debug('--instantiateAll was set, ignoring required list and instantiating all properties.'); +export function logRequiredMessage(logger: Logger, required: string[], generateAll: boolean) { + if (generateAll) { + logger.debug('--generateAll was set, ignoring required list and generating all properties.'); } else { logger.debug('Required properties: ' + required); } diff --git a/shared/src/commands/validate/output-formats/junit-output.spec.ts b/shared/src/commands/validate/output-formats/junit-output.spec.ts index a80be93c..1afe6c5a 100644 --- a/shared/src/commands/validate/output-formats/junit-output.spec.ts +++ b/shared/src/commands/validate/output-formats/junit-output.spec.ts @@ -21,7 +21,7 @@ const spectralValidationOutput: ValidationOutput[] = [ new ValidationOutput( 'no-placeholder-properties-numerical', 'warning', - 'Numerical placeholder (-1) detected in instantiated pattern.', + 'Numerical placeholder (-1) detected in architecture.', '/nodes/0/interfaces/0/port' ) ]; diff --git a/shared/src/commands/validate/validate.spec.ts b/shared/src/commands/validate/validate.spec.ts index ab4dfeca..015b4830 100644 --- a/shared/src/commands/validate/validate.spec.ts +++ b/shared/src/commands/validate/validate.spec.ts @@ -66,14 +66,14 @@ describe('validate-all', () => { }); - it('returns validation error when the pattern instantiation file cannot be found in the input path', async () => { + it('returns validation error when the architecture file cannot be found in the input path', async () => { await expect(validate('../doesNotExists/api-gateway-implementation.json', 'test_fixtures/api-gateway.json', metaSchemaLocation, debugDisabled)) .rejects .toThrow(); expect(mockExit).toHaveBeenCalledWith(1); }); - it('returns validation error when the pattern instantiation file does not contain JSON', async () => { + it('returns validation error when the architecture file does not contain JSON', async () => { await expect(validate('test_fixtures/api-gateway-implementation.json', 'test_fixtures/markdown.md', metaSchemaLocation, debugDisabled)) .rejects .toThrow(); @@ -90,7 +90,7 @@ describe('validate-all', () => { expect(mockExit).toHaveBeenCalledWith(1); }); - it('exits with error when the pattern instantiation URL returns a 404', async () => { + it('exits with error when the architecture URL returns a 404', async () => { const apiGateway = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway.json'), 'utf8'); fetchMock.mock('http://exist/api-gateway.json', apiGateway); @@ -103,7 +103,7 @@ describe('validate-all', () => { expect(mockExit).toHaveBeenCalledWith(1); }); - it('exits with error when the pattern instantiation file at given URL returns non JSON response', async () => { + it('exits with error when the architecture file at given URL returns non JSON response', async () => { const apiGateway = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway.json'), 'utf8'); const markdown = ' #This is markdown'; @@ -126,13 +126,13 @@ describe('validate-all', () => { }); - it('has error when the pattern instantiation does not match the json schema', async () => { + it('has error when the architecture does not match the json schema', async () => { const apiGateway = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway.json'), 'utf8'); fetchMock.mock('http://exist/api-gateway.json', apiGateway); - const apiGatewayInstantiation = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway-implementation-that-does-not-match-schema.json'), 'utf8'); - fetchMock.mock('https://exist/api-gateway-implementation.json', apiGatewayInstantiation); + const apiGatewayArchitecture = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway-implementation-that-does-not-match-schema.json'), 'utf8'); + fetchMock.mock('https://exist/api-gateway-implementation.json', apiGatewayArchitecture); const response = await validate('https://exist/api-gateway-implementation.json', 'http://exist/api-gateway.json', metaSchemaLocation, debugDisabled); @@ -143,7 +143,7 @@ describe('validate-all', () => { expect(response.allValidationOutputs().length).toBeGreaterThan(0); }); - it('has error when the pattern instantiation does not pass all the spectral validations', async () => { + it('has error when the architecture does not pass all the spectral validations', async () => { const expectedSpectralOutput: ISpectralDiagnostic[] = [ { @@ -160,8 +160,8 @@ describe('validate-all', () => { const apiGateway = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway.json'), 'utf8'); fetchMock.mock('http://exist/api-gateway.json', apiGateway); - const apiGatewayInstantiation = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway-implementation-that-does-not-pass-the-spectral-validation.json'), 'utf8'); - fetchMock.mock('https://exist/api-gateway-implementation.json', apiGatewayInstantiation); + const apiGatewayArchitecture = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway-implementation-that-does-not-pass-the-spectral-validation.json'), 'utf8'); + fetchMock.mock('https://exist/api-gateway-implementation.json', apiGatewayArchitecture); const response = await validate('https://exist/api-gateway-implementation.json', 'http://exist/api-gateway.json', metaSchemaLocation, debugDisabled); expect(response).not.toBeNull(); @@ -187,8 +187,8 @@ describe('validate-all', () => { const apiGateway = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway-with-no-relationships.json'), 'utf8'); fetchMock.mock('http://exist/api-gateway.json', apiGateway); - const apiGatewayInstantiation = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway-implementation.json'), 'utf8'); - fetchMock.mock('https://exist/api-gateway-implementation.json', apiGatewayInstantiation); + const apiGatewayArchitecture = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway-implementation.json'), 'utf8'); + fetchMock.mock('https://exist/api-gateway-implementation.json', apiGatewayArchitecture); const response = await validate('https://exist/api-gateway-implementation.json', 'http://exist/api-gateway.json', metaSchemaLocation, debugDisabled); expect(response).not.toBeNull(); @@ -215,8 +215,8 @@ describe('validate-all', () => { const apiGateway = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway.json'), 'utf8'); fetchMock.mock('http://exist/api-gateway.json', apiGateway); - const apiGatewayInstantiation = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway-implementation.json'), 'utf8'); - fetchMock.mock('https://exist/api-gateway-implementation.json', apiGatewayInstantiation); + const apiGatewayArchitecture = readFileSync(path.resolve(__dirname, '../../../test_fixtures/api-gateway-implementation.json'), 'utf8'); + fetchMock.mock('https://exist/api-gateway-implementation.json', apiGatewayArchitecture); const response = await validate('https://exist/api-gateway-implementation.json', 'http://exist/api-gateway.json', metaSchemaLocation, debugDisabled); expect(response).not.toBeNull(); diff --git a/shared/src/commands/validate/validate.ts b/shared/src/commands/validate/validate.ts index 5e63f25e..d84dfcef 100644 --- a/shared/src/commands/validate/validate.ts +++ b/shared/src/commands/validate/validate.ts @@ -3,7 +3,7 @@ import { existsSync, promises as fs, readdirSync, readFileSync, statSync } from import { Spectral, ISpectralDiagnostic, RulesetDefinition } from '@stoplight/spectral-core'; import validationRulesForPattern from '../../spectral/rules-pattern'; -import validationRulesForInstantiation from '../../spectral/rules-instantiation'; +import validationRulesForArchitecture from '../../spectral/rules-architecture'; import { DiagnosticSeverity } from '@stoplight/types'; import * as winston from 'winston'; import { initLogger } from '../helper.js'; @@ -17,13 +17,13 @@ let logger: winston.Logger; // defined later at startup /** * Merge the results from two Spectral validations together, combining any errors/warnings. * @param spectralResultPattern Spectral results from the pattern validation - * @param spectralResultInstantiation Spectral results from the instantiation validation + * @param spectralResultArchitecture Spectral results from the architecture validation * @returns A new SpectralResult with the error/warning status propagated and the results concatenated. */ -function mergeSpectralResults(spectralResultPattern: SpectralResult, spectralResultInstantiation: SpectralResult): SpectralResult { - const errors: boolean = spectralResultPattern.errors || spectralResultInstantiation.errors; - const warnings: boolean = spectralResultPattern.warnings || spectralResultInstantiation.warnings; - const spectralValidations = spectralResultPattern.spectralIssues.concat(spectralResultInstantiation.spectralIssues); +function mergeSpectralResults(spectralResultPattern: SpectralResult, spectralResultArchitecture: SpectralResult): SpectralResult { + const errors: boolean = spectralResultPattern.errors || spectralResultArchitecture.errors; + const warnings: boolean = spectralResultPattern.warnings || spectralResultArchitecture.warnings; + const spectralValidations = spectralResultPattern.spectralIssues.concat(spectralResultArchitecture.spectralIssues); return new SpectralResult(warnings, errors, spectralValidations); } @@ -235,33 +235,33 @@ export function stripRefs(obj: object): string { /** * This is essentially the old function, just wrapped into the nicer functions. - * @param jsonSchemaInstantiationLocation + * @param jsonSchemaArchitectureLocation * @param jsonSchemaLocation * @param metaSchemaPath * @param debug * @param failOnWarnings */ export async function validateAndExitConditionally( - jsonSchemaInstantiationLocation: string, + jsonSchemaArchitectureLocation: string, jsonSchemaLocation: string, metaSchemaPath: string, debug: boolean = false, failOnWarnings: boolean = false ): Promise { - const outcome = await validate(jsonSchemaInstantiationLocation, jsonSchemaLocation, metaSchemaPath, debug); + const outcome = await validate(jsonSchemaArchitectureLocation, jsonSchemaLocation, metaSchemaPath, debug); exitBasedOffOfValidationOutcome(outcome, failOnWarnings); } /** * Validation - with simple input parameters and output validation outcomes. - * @param jsonSchemaInstantiationLocation + * @param jsonSchemaArchitectureLocation * @param jsonSchemaLocation * @param metaSchemaPath * @param debug * @returns */ export async function validate( - jsonSchemaInstantiationLocation: string, + jsonSchemaArchitectureLocation: string, jsonSchemaLocation: string, metaSchemaPath: string, debug: boolean = false): Promise { @@ -279,24 +279,24 @@ export async function validate( const spectralResultForPattern: SpectralResult = await runSpectralValidations(stripRefs(jsonSchema), validationRulesForPattern); - if (jsonSchemaInstantiationLocation === undefined) { + if (jsonSchemaArchitectureLocation === undefined) { return validatePatternOnly(spectralResultForPattern, jsonSchema, ajv); } const validateSchema = await ajv.compileAsync(jsonSchema); - logger.info(`Loading pattern instantiation from : ${jsonSchemaInstantiationLocation}`); - const jsonSchemaInstantiation = await getFileFromUrlOrPath(jsonSchemaInstantiationLocation); + logger.info(`Loading architecture from : ${jsonSchemaArchitectureLocation}`); + const jsonSchemaArchitecture = await getFileFromUrlOrPath(jsonSchemaArchitectureLocation); - const spectralResultForInstantiation: SpectralResult = await runSpectralValidations(jsonSchemaInstantiation, validationRulesForInstantiation); + const spectralResultForArchitecture: SpectralResult = await runSpectralValidations(jsonSchemaArchitecture, validationRulesForArchitecture); - const spectralResult = mergeSpectralResults(spectralResultForPattern, spectralResultForInstantiation); + const spectralResult = mergeSpectralResults(spectralResultForPattern, spectralResultForArchitecture); errors = spectralResult.errors; warnings = spectralResult.warnings; let jsonSchemaValidations = []; - if (!validateSchema(jsonSchemaInstantiation)) { + if (!validateSchema(jsonSchemaArchitecture)) { logger.debug(`JSON Schema validation raw output: ${prettifyJson(validateSchema.errors)}`); errors = true; jsonSchemaValidations = convertJsonSchemaIssuesToValidationOutputs(validateSchema.errors); @@ -319,7 +319,7 @@ export async function validate( * @param failOnWarnings Whether or not to treat a warning as a failure in the validation process. */ function validatePatternOnly(spectralValidationResults: SpectralResult, patternSchema: object, ajv: Ajv2020): ValidationOutcome { - logger.debug('Pattern Instantiation was not provided, only the JSON Schema will be validated'); + logger.debug('Architecture was not provided, only the JSON Schema will be validated'); let errors = spectralValidationResults.errors; const warnings = spectralValidationResults.warnings; const jsonSchemaErrors = []; @@ -335,9 +335,9 @@ function validatePatternOnly(spectralValidationResults: SpectralResult, patternS } function extractSpectralRuleNames(): string[] { - const instantiationRuleNames = getRuleNamesFromRuleset(validationRulesForInstantiation); + const architectureRuleNames = getRuleNamesFromRuleset(validationRulesForArchitecture); const patternRuleNames = getRuleNamesFromRuleset(validationRulesForPattern); - return instantiationRuleNames.concat(patternRuleNames); + return architectureRuleNames.concat(patternRuleNames); } function getRuleNamesFromRuleset(ruleset: RulesetDefinition): string[] { diff --git a/shared/src/commands/visualize/calmToDot.spec.ts b/shared/src/commands/visualize/calmToDot.spec.ts index af657619..e7977e59 100644 --- a/shared/src/commands/visualize/calmToDot.spec.ts +++ b/shared/src/commands/visualize/calmToDot.spec.ts @@ -1,4 +1,4 @@ -import { CALMInstantiation } from '../../types'; +import { CALMArchitecture } from '../../types'; import calmToDot from './calmToDot'; jest.mock('../helper.js', () => { @@ -14,7 +14,7 @@ jest.mock('../helper.js', () => { }); describe('calmToDot', () => { - let calm: CALMInstantiation; + let calm: CALMArchitecture; beforeEach(() => { calm = { diff --git a/shared/src/commands/visualize/calmToDot.ts b/shared/src/commands/visualize/calmToDot.ts index 2532f26b..33a484b1 100644 --- a/shared/src/commands/visualize/calmToDot.ts +++ b/shared/src/commands/visualize/calmToDot.ts @@ -1,5 +1,5 @@ import { Digraph, Subgraph, Node, Edge, toDot, attribute } from 'ts-graphviz'; -import { CALMInstantiation, CALMComposedOfRelationship, CALMConnectsRelationship, CALMInteractsRelationship, CALMNode, CALMRelationship, CALMDeployedInRelationship } from '../../types'; +import { CALMArchitecture, CALMComposedOfRelationship, CALMConnectsRelationship, CALMInteractsRelationship, CALMNode, CALMRelationship, CALMDeployedInRelationship } from '../../types'; import { initLogger } from '../helper.js'; import winston from 'winston'; @@ -7,7 +7,7 @@ let logger: winston.Logger; const idToNode: {[id: string]: Node} = {}; -export default function(calm: CALMInstantiation, debug: boolean = false): string { +export default function(calm: CALMArchitecture, debug: boolean = false): string { logger = initLogger(debug); const G = new Digraph({ diff --git a/shared/src/commands/visualize/visualize.spec.ts b/shared/src/commands/visualize/visualize.spec.ts index 6a11149e..927dbb25 100644 --- a/shared/src/commands/visualize/visualize.spec.ts +++ b/shared/src/commands/visualize/visualize.spec.ts @@ -1,6 +1,6 @@ import { readFileSync, writeFileSync } from 'node:fs'; import * as graphviz from 'graphviz-cli'; -import { visualizeInstantiation, visualizePattern } from './visualize'; +import { visualizeArchitecture, visualizePattern } from './visualize'; import { generate } from '../generate/generate'; jest.mock('node:fs', () => { @@ -48,7 +48,7 @@ describe('visualizer', () => { }); }); - describe('visualize instantiation', () => { + describe('visualize architecture', () => { beforeEach(() => { (readFileSync as jest.Mock).mockReturnValue(` @@ -68,21 +68,21 @@ describe('visualizer', () => { it('reads from the given input file', async () => { jest.spyOn(graphviz, 'renderGraphFromSource').mockResolvedValue(''); - await visualizeInstantiation('./input.json', './output.svg', false); + await visualizeArchitecture('./input.json', './output.svg', false); expect(readFileSync).toHaveBeenCalledWith('./input.json', 'utf-8'); }); it('writes to the given output file', async () => { jest.spyOn(graphviz, 'renderGraphFromSource').mockResolvedValue(''); - await visualizeInstantiation('./input.json', './output.svg', false); + await visualizeArchitecture('./input.json', './output.svg', false); expect(writeFileSync).toHaveBeenCalledWith('./output.svg', ''); }); it('doesnt write if an error is thrown', async () => { jest.spyOn(graphviz, 'renderGraphFromSource').mockRejectedValue(new Error()); - await expect(visualizeInstantiation('./input.json', './output.svg', false)) + await expect(visualizeArchitecture('./input.json', './output.svg', false)) .rejects .toThrow(); @@ -116,7 +116,7 @@ describe('visualizer', () => { jest.resetAllMocks(); }); - it('generates instantiation from the given input file', async () => { + it('generates architecture from the given input file', async () => { jest.spyOn(graphviz, 'renderGraphFromSource').mockResolvedValue(''); await visualizePattern('./input.json', './output.svg', false); diff --git a/shared/src/commands/visualize/visualize.ts b/shared/src/commands/visualize/visualize.ts index 245278d2..e1d69fdb 100644 --- a/shared/src/commands/visualize/visualize.ts +++ b/shared/src/commands/visualize/visualize.ts @@ -8,22 +8,22 @@ import { generate } from '../generate/generate.js'; let logger: winston.Logger; -export async function visualize(instantiation: string): Promise { +export async function visualize(architecture: string): Promise { try { - const dot = calmToDot(JSON.parse(instantiation)); + const dot = calmToDot(JSON.parse(architecture)); return (await instance()).render(dot, { format: 'svg', engine: 'dot' }).output; } catch (error: unknown) { console.error(error); - return 'Error creating SVG: Instantiation JSON is invalid'; + return 'Error creating SVG: Architecture JSON is invalid'; } } -export async function visualizeInstantiation(instantiationPath: string, output: string, debug: boolean) { +export async function visualizeArchitecture(architecturePath: string, output: string, debug: boolean) { logger = initLogger(debug); - logger.info(`Reading CALM file from [${instantiationPath}]`); - const calm = fs.readFileSync(instantiationPath, 'utf-8'); + logger.info(`Reading CALM file from [${architecturePath}]`); + const calm = fs.readFileSync(architecturePath, 'utf-8'); logger.info('Generating an SVG from input'); @@ -47,12 +47,12 @@ export async function visualizePattern(patternPath: string, output: string, debu logger = initLogger(debug); // TODO add a path to load schemas and generate intelligently - const instantiation = await generate(patternPath, debug, true); + const architecture = await generate(patternPath, debug, true); logger.info('Generating an SVG from input'); try { - const dot = calmToDot(instantiation, debug); + const dot = calmToDot(architecture, debug); logger.debug(`Generated the following dot: ${dot} `); diff --git a/shared/src/index.ts b/shared/src/index.ts index 8775ad7a..41656f59 100644 --- a/shared/src/index.ts +++ b/shared/src/index.ts @@ -1,5 +1,5 @@ export { validate, formatOutput as getFormattedOutput, validateAndExitConditionally, exitBasedOffOfValidationOutcome } from './commands/validate/validate.js'; -export { visualizeInstantiation, visualizePattern, visualize } from './commands/visualize/visualize.js'; +export { visualizeArchitecture as visualizeArchitecture, visualizePattern, visualize } from './commands/visualize/visualize.js'; export { OutputFormat } from './commands/validate/validate.js'; export { runGenerate } from './commands/generate/generate.js'; export { ValidationOutput } from './commands/validate/validation.output.js'; diff --git a/shared/src/spectral/functions/instantiation/ids-are-unique.ts b/shared/src/spectral/functions/architecture/ids-are-unique.ts similarity index 100% rename from shared/src/spectral/functions/instantiation/ids-are-unique.ts rename to shared/src/spectral/functions/architecture/ids-are-unique.ts diff --git a/shared/src/spectral/functions/instantiation/interface-id-exists.ts b/shared/src/spectral/functions/architecture/interface-id-exists.ts similarity index 100% rename from shared/src/spectral/functions/instantiation/interface-id-exists.ts rename to shared/src/spectral/functions/architecture/interface-id-exists.ts diff --git a/shared/src/spectral/functions/instantiation/node-has-relationship.ts b/shared/src/spectral/functions/architecture/node-has-relationship.ts similarity index 100% rename from shared/src/spectral/functions/instantiation/node-has-relationship.ts rename to shared/src/spectral/functions/architecture/node-has-relationship.ts diff --git a/shared/src/spectral/functions/instantiation/node-id-exists.ts b/shared/src/spectral/functions/architecture/node-id-exists.ts similarity index 100% rename from shared/src/spectral/functions/instantiation/node-id-exists.ts rename to shared/src/spectral/functions/architecture/node-id-exists.ts diff --git a/shared/src/spectral/pattern/validation-rules.yaml b/shared/src/spectral/pattern/validation-rules.yaml index 46746fcb..bc23509e 100644 --- a/shared/src/spectral/pattern/validation-rules.yaml +++ b/shared/src/spectral/pattern/validation-rules.yaml @@ -28,7 +28,7 @@ rules: pattern-has-no-placeholder-properties-numerical: description: Should not contain numerical placeholder properties set to -1 - message: Numerical placeholder (-1) detected in instantiated pattern. + message: Numerical placeholder (-1) detected in architecture. severity: warn given: "$..*" then: @@ -37,7 +37,7 @@ rules: pattern-has-no-placeholder-properties-string: description: Should not contain placeholder values with pattern {{ PLACEHOLDER_NAME }} - message: String placeholder detected in instantiated pattern. + message: String placeholder detected in architecture. severity: warn given: "$..*" then: diff --git a/shared/src/spectral/rules-instantiation.ts b/shared/src/spectral/rules-architecture.ts similarity index 74% rename from shared/src/spectral/rules-instantiation.ts rename to shared/src/spectral/rules-architecture.ts index 3d2cb6f5..dd6752fc 100644 --- a/shared/src/spectral/rules-instantiation.ts +++ b/shared/src/spectral/rules-architecture.ts @@ -1,15 +1,15 @@ import { RulesetDefinition } from '@stoplight/spectral-core'; import { pattern, truthy } from '@stoplight/spectral-functions'; import { numericalPlaceHolder } from './functions/helper-functions'; -import { idsAreUnique } from './functions/instantiation/ids-are-unique'; -import { nodeIdExists } from './functions/instantiation/node-id-exists'; -import { interfaceIdExists } from './functions/instantiation/interface-id-exists'; -import { nodeHasRelationship } from './functions/instantiation/node-has-relationship'; +import { idsAreUnique } from './functions/architecture/ids-are-unique'; +import { nodeIdExists } from './functions/architecture/node-id-exists'; +import { interfaceIdExists } from './functions/architecture/interface-id-exists'; +import { nodeHasRelationship } from './functions/architecture/node-has-relationship'; -const instantiationRules: RulesetDefinition = { +const architectureRules: RulesetDefinition = { rules: { - 'instantiation-has-nodes-relationships': { + 'architecture-has-nodes-relationships': { description: 'Has top level nodes and relationships', message: 'Should have nodes and relationships as top level properties on the CALM document', severity: 'error', @@ -26,7 +26,7 @@ const instantiationRules: RulesetDefinition = { ], }, - 'instantiation-has-no-empty-properties': { + 'architecture-has-no-empty-properties': { description: 'Must not contain string properties set to the empty string or numerical properties set to zero', message: 'All properties must be set to a nonempty, nonzero value.', severity: 'error', @@ -36,9 +36,9 @@ const instantiationRules: RulesetDefinition = { }, }, - 'instantiation-has-no-placeholder-properties-numerical': { + 'architecture-has-no-placeholder-properties-numerical': { description: 'Should not contain numerical placeholder properties set to -1', - message: 'Numerical placeholder (-1) detected in instantiated pattern.', + message: 'Numerical placeholder (-1) detected in architecture.', severity: 'warn', given: '$..*', then: { @@ -46,9 +46,9 @@ const instantiationRules: RulesetDefinition = { }, }, - 'instantiation-has-no-placeholder-properties-string': { + 'architecture-has-no-placeholder-properties-string': { description: 'Should not contain placeholder values with pattern {{ PLACEHOLDER_NAME }}', - message: 'String placeholder detected in instantiated pattern.', + message: 'String placeholder detected in architecture.', severity: 'warn', given: '$..*', then: { @@ -59,9 +59,9 @@ const instantiationRules: RulesetDefinition = { }, }, - 'instantiation-has-no-placeholder-properties-boolean': { + 'architecture-has-no-placeholder-properties-boolean': { description: 'Should not contain placeholder values with pattern {{ BOOLEAN_[property name] }}', - message: 'Boolean placeholder detected in instantiated pattern.', + message: 'Boolean placeholder detected in architecture.', severity: 'warn', given: '$..*', then: { @@ -72,7 +72,7 @@ const instantiationRules: RulesetDefinition = { }, }, - 'relationship-references-existing-nodes-in-instantiation': { + 'relationship-references-existing-nodes-in-architecture': { description: 'Relationships must reference existing nodes', severity: 'error', message: '{{error}}', @@ -89,7 +89,7 @@ const instantiationRules: RulesetDefinition = { ], }, - 'connects-relationship-references-existing-nodes-in-instantiation': { + 'connects-relationship-references-existing-nodes-in-architecture': { description: 'Connects relationships must reference existing nodes', severity: 'error', message: '{{error}}', @@ -100,7 +100,7 @@ const instantiationRules: RulesetDefinition = { }, }, - 'referenced-interfaces-defined-in-instantiation': { + 'referenced-interfaces-defined-in-architecture': { description: 'Referenced interfaces must be defined ', severity: 'error', message: '{{error}}', @@ -110,7 +110,7 @@ const instantiationRules: RulesetDefinition = { }, }, - 'composition-relationships-reference-existing-nodes-in-instantiation': { + 'composition-relationships-reference-existing-nodes-in-architecture': { description: 'All nodes in a composition relationship must reference existing nodes', severity: 'error', message: '{{error}}', @@ -120,7 +120,7 @@ const instantiationRules: RulesetDefinition = { }, }, - 'instantiation-nodes-must-be-referenced': { + 'architecture-nodes-must-be-referenced': { description: 'Nodes must be referenced by at least one relationship.', severity: 'warn', message: '{{error}}', @@ -130,7 +130,7 @@ const instantiationRules: RulesetDefinition = { }, }, - 'unique-ids-must-be-unique-in-instantiation': { + 'unique-ids-must-be-unique-in-architecture': { description: 'Unique IDs cannot be reused.', severity: 'error', message: '{{error}}', @@ -142,4 +142,4 @@ const instantiationRules: RulesetDefinition = { } }; -export default instantiationRules; \ No newline at end of file +export default architectureRules; \ No newline at end of file diff --git a/shared/src/spectral/rules-pattern.ts b/shared/src/spectral/rules-pattern.ts index 8c546027..9ff3e8c0 100644 --- a/shared/src/spectral/rules-pattern.ts +++ b/shared/src/spectral/rules-pattern.ts @@ -36,7 +36,7 @@ const patternRules: RulesetDefinition = { }, 'pattern-has-no-placeholder-properties-numerical': { description: 'Should not contain numerical placeholder properties set to -1', - message: 'Numerical placeholder (-1) detected in instantiated pattern.', + message: 'Numerical placeholder (-1) detected in architecture.', severity: 'warn', given: '$..*', then: { @@ -45,7 +45,7 @@ const patternRules: RulesetDefinition = { }, 'pattern-has-no-placeholder-properties-string': { description: 'Should not contain placeholder values with pattern {{ PLACEHOLDER_NAME }}', - message: 'String placeholder detected in instantiated pattern.', + message: 'String placeholder detected in architecture.', severity: 'warn', given: '$..*', then: { diff --git a/shared/src/types.ts b/shared/src/types.ts index fe6c0100..67446d11 100644 --- a/shared/src/types.ts +++ b/shared/src/types.ts @@ -1,4 +1,4 @@ -export interface CALMInstantiation { +export interface CALMArchitecture { nodes: CALMNode[], relationships: CALMRelationship[] }