From 0920cceed7935c3b58a486081c8d5ff7188e2bf3 Mon Sep 17 00:00:00 2001 From: Aidan McPhelim Date: Tue, 4 Jun 2024 15:17:01 +0100 Subject: [PATCH 1/2] update readme and create developer guide --- cli/DEVELOPER_GUIDE.md | 28 +++++++++++ cli/README.md | 102 +++++++++++++++++++++++++---------------- 2 files changed, 91 insertions(+), 39 deletions(-) create mode 100644 cli/DEVELOPER_GUIDE.md diff --git a/cli/DEVELOPER_GUIDE.md b/cli/DEVELOPER_GUIDE.md new file mode 100644 index 00000000..829e120d --- /dev/null +++ b/cli/DEVELOPER_GUIDE.md @@ -0,0 +1,28 @@ +# Developing the CALM CLI + +## Building & linking the CLI + +Clone the project and run the following commands: + +```shell +npm install +npm run build +npx link +``` + +When you've made a change to the CLI and want to test it out, you can rerun the build and link steps. +This will make the CLI available on your local `node_modules` path. + +`npx link` uses the `link` package to symlink the `calm` executable in `node_modules/.bin` to your locally-built CLI. + +Note: you can also use `npm link` but this installs to your global package registry. +This will make the executable available as just `calm`, but will pollute your global NPM profile and may require `sudo` depending on your OS. + +## Additional Commands + +Some other commands that you might find useful during development include: + +- `npm run lint` to point out any lint errors in the code +- `npm run test` to run the tests against the code base + +You can find the full list by examining the `package.json` diff --git a/cli/README.md b/cli/README.md index e68a4f2f..98515f50 100644 --- a/cli/README.md +++ b/cli/README.md @@ -1,24 +1,7 @@ ## CALM CLI A command line interface to interact with the CALM schema. - -## Building & linking the CLI - -Clone the project and run the following commands: - -```shell -npm install -npm run build -npx link -``` - -When you've made a change to the CLI and want to test it out, you can rerun the build and link steps. -This will make the CLI available on your local `node_modules` path. - -`npx link` uses the `link` package to symlink the `calm` executable in `node_modules/.bin` to your locally-built CLI. - -Note: you can also use `npm link` but this installs to your global package registry. -This will make the executable available as just `calm`, but will pollute your global NPM profile and may require `sudo` depending on your OS. +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. ### Using the CLI @@ -41,43 +24,39 @@ Commands: help [command] display help for command ``` -### Visualizing the CALM schema - -```shell -% npx calm visualize --help -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. - -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) - -h, --help display help for command -``` - ### Generating an instantiation from a CALM pattern file +This command lets you create a shell of an instantiation from a pattern file. +You can try it out using the example patterns provided in this repo under `calm/pattern`. + ```shell -npx calm generate --help +% calm generate --help Usage: calm generate [options] Generate an instantiation 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. - -s, --schemaDirectory Path to a directory of schemas to be used when instantiating patterns. - -a, --instantiateAll Instantiate ALL properties in the pattern, ignoring the 'required' field. (default: false) + -o, --output Path location at which to output the generated file. (default: "instantiation.json") + -s, --schemaDirectory Path to directory containing schemas to use in instantiation -v, --verbose Enable verbose logging. (default: false) + -a, --instantiateAll Instantiate 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. + +```shell +% calm generate -p calm/pattern/api-gateway.json +``` + ### Validating a CALM instantiation +This command will tell you if an instantiation 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 -% npx calm validate --help +% calm validate --help Usage: calm validate [options] Validate that an instantiation conforms to a given CALM pattern. @@ -90,5 +69,50 @@ Options: -o, --output Path location at which to output the generated file. -v, --verbose Enable verbose logging. (default: false) -h, --help display help for command +``` + +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. + +If you were to try and generate an instantiation from the api-pattern, and then validate the instantation against that pattern like this + +```shell +% calm generate -p calm/pattern/api-gateway.json +% calm validate -p calm/pattern/api-pattern.json -i instantiation.json +``` + +You would get an output which includes a warning like this: + +```json +... +{ + "code": "instantiation-has-no-placeholder-properties-string", + "severity": "warning", + "message": "String placeholder detected in instantiated pattern.", + "path": "/nodes/2/interfaces/0/host" +} +... +``` + +which is just letting you know that you have left in a placeholder value which might have been generated with the generate command. +This isn't a full break, but it implies that you've forgotten to fill out a detail in your architecture. + +### 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. +You can then open up that file in the browser to see a box and line diagram which represents your architecture. + +```shell +% calm visualize --help +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. + -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) + -h, --help display help for command ``` From e92136c9157afbe1b393725fdb1d97da8a9c4c03 Mon Sep 17 00:00:00 2001 From: Aidan McPhelim Date: Wed, 5 Jun 2024 09:23:14 +0100 Subject: [PATCH 2/2] added install instructions --- cli/README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/cli/README.md b/cli/README.md index 98515f50..c634ba62 100644 --- a/cli/README.md +++ b/cli/README.md @@ -3,7 +3,13 @@ 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. -### Using the CLI +### Getting Started + +Install the CLI on to your machine with this command: + +```shell +% npm install -g @finos/calm-cli +``` Type `calm` into your terminal, and you should see the help text printed out.