@aml-org/ruleset-development-cli

ruleset-development-cli

The ruleset-development-cli provides tooling to write, test and debug AMF Governance Rulesets that can then be applied over RAML, OAS, GraphQL, gRPC or abitrary JSON-LD documents using the AMF Custom Validator[https://github.com/aml-org/amf-custom-validator/] or any Open Policy Agent (OPA) compatible runtime.

You can find a complete explanation and tutorial about how to write rules here. You can also open the tutorial just using the following CLI command:

$ ruleset-development-cli tutorial

Development flow

• Create a new ruleset project using the ruleset-development-cli [ruleset-name] from the directory for the ruleset
• Create a new rule to the project with description and the right severity level using the ruleset-development-cli new rule [rule-name] command
• Add positive and negative examples in the target specification languages using the ruleset-development-cli new example [rule-name] [example-id] command
• Inspect the JSON-LD model of the examples if required to understand how to write the rule using the ruleset-development-cli model dump command
• Check all the positive and negative examples for the ruleset using the ruleset-development-cli test command
• If you need to debug the OPA Rego code generated for the rule use the ruleset-development-cli test command with the --debug flag to find the rego code for the rulest and the input JSON for the validator for every example
• When ready to publish use the ruleset-development-cli clean command to remove debug files and then use the ruleset-development-cli build command to generate the consolidated ruleset YAML file with all the rules

• Development flow
• Usage
• Commands

Usage

$ npm install -g @aml-org/ruleset-development-cli
$ ruleset-development-cli COMMAND
running command...
$ ruleset-development-cli (--version)
@aml-org/ruleset-development-cli/0.3.9 darwin-x64 node-v14.18.1
$ ruleset-development-cli --help [COMMAND]
USAGE
  $ ruleset-development-cli COMMAND
...

Commands

• ruleset-development-cli build
• ruleset-development-cli clean
• ruleset-development-cli help [COMMAND]
• ruleset-development-cli lint
• ruleset-development-cli model dump
• ruleset-development-cli model inspect RULENAME ID
• ruleset-development-cli new NAME [DEFAULTSPEC]
• ruleset-development-cli new example RULENAME ID
• ruleset-development-cli new rule NAME
• ruleset-development-cli plugins
• ruleset-development-cli plugins:install PLUGIN...
• ruleset-development-cli plugins:inspect PLUGIN...
• ruleset-development-cli plugins:install PLUGIN...
• ruleset-development-cli plugins:link PLUGIN
• ruleset-development-cli plugins:uninstall PLUGIN...
• ruleset-development-cli plugins:uninstall PLUGIN...
• ruleset-development-cli plugins:uninstall PLUGIN...
• ruleset-development-cli plugins update
• ruleset-development-cli test
• ruleset-development-cli trace RULENAME ID
• ruleset-development-cli tutorial

ruleset-development-cli build

generates a consolidated ruleset file with all the rules

USAGE
  $ ruleset-development-cli build [-l <value>]

FLAGS
  -l, --location=<value>  path where the project has been created

DESCRIPTION
  generates a consolidated ruleset file with all the rules

EXAMPLES
  $ ruleset-development-cli build

  $ ruleset-development-cli build -l /development/my-ruleset-project

See code: dist/commands/build.ts

ruleset-development-cli clean

cleans debug and model data

USAGE
  $ ruleset-development-cli clean [-l <value>]

FLAGS
  -l, --location=<value>  path where the project has been created

DESCRIPTION
  cleans debug and model data

EXAMPLES
  $ ruleset-development-cli clean

  $ ruleset-development-cli clean -l /development/my-ruleset-project

See code: dist/commands/clean.ts

ruleset-development-cli help [COMMAND]

Display help for ruleset-development-cli.

USAGE
  $ ruleset-development-cli help [COMMAND] [-n]

ARGUMENTS
  COMMAND  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for ruleset-development-cli.

See code: @oclif/plugin-help

ruleset-development-cli lint

Validates the rules syntax without testing any examples

USAGE
  $ ruleset-development-cli lint [-l <value>]

FLAGS
  -l, --location=<value>  path where the project has been created

DESCRIPTION
  Validates the rules syntax without testing any examples

EXAMPLES
  $ ruleset-development-cli lint

  $ ruleset-development-cli lint -l /development/my-ruleset-project

See code: dist/commands/lint.ts

ruleset-development-cli model dump

serializes the JSON-LD model for an example

USAGE
  $ ruleset-development-cli model dump [-l <value>] [-f <value>]

FLAGS
  -f, --filter=<value>    regex used to filter the examples that are going to be validated
  -l, --location=<value>  path where the project will be created

DESCRIPTION
  serializes the JSON-LD model for an example

EXAMPLES
  $ ruleset-development-cli model dump

ruleset-development-cli model inspect RULENAME ID

describe the command here

USAGE
  $ ruleset-development-cli model inspect [RULENAME] [ID] [-l <value>]

ARGUMENTS
  RULENAME  name of the rule where the example will be added
  ID        id of the example

FLAGS
  -l, --location=<value>  path where the project will be created

DESCRIPTION
  describe the command here

EXAMPLES
  $ ruleset-development-cli model inspect

ruleset-development-cli new NAME [DEFAULTSPEC]

Generates a new ruleset project

USAGE
  $ ruleset-development-cli new [NAME] [DEFAULTSPEC] [-l <value>] [-s <value>]

ARGUMENTS
  NAME         name of the ruleset
  DEFAULTSPEC  default spec for new examples

FLAGS
  -l, --location=<value>     path where the project will be created
  -s, --defaultSpec=<value>  default spec for examples at new rules creation

DESCRIPTION
  Generates a new ruleset project

EXAMPLES
  $ ruleset-development-cli new

  $ ruleset-development-cli new -l /development/my-ruleset-project

  $ ruleset-development-cli new -l /development/my-ruleset-project -s oas

See code: dist/commands/new/index.ts

ruleset-development-cli new example RULENAME ID

generates a new example for a rule

USAGE
  $ ruleset-development-cli new example [RULENAME] [ID] [-f <value>] [-l <value>] [-o <value>]

ARGUMENTS
  RULENAME  name of the rule where the example will be added
  ID        id of the example

FLAGS
  -f, --format=<value>    spec format for the example (oas, raml, asyncapi, graphql, grpc)
  -l, --location=<value>  path where the project has been created
  -o, --only=<value>      generate only positive|negative example

DESCRIPTION
  generates a new example for a rule

EXAMPLES
  $ ruleset-development-cli new example mandatory-tags ex1

  $ ruleset-development-cli new example mandatory-tags ex1 -f grpc

  $ ruleset-development-cli new example mandatory-tags ex1 -f graphql --only positive

ruleset-development-cli new rule NAME

creates a new rule for the ruleset

USAGE
  $ ruleset-development-cli new rule [NAME] [-s <value>] [-m <value>] [-l <value>]

ARGUMENTS
  NAME  name of the rule

FLAGS
  -l, --location=<value>  path where the project has been created
  -m, --message=<value>   error message for the rule
  -s, --level=<value>     severity level for the rule

DESCRIPTION
  creates a new rule for the ruleset

EXAMPLES
  $ ruleset-development-cli new rule mandatory-tags

  $ ruleset-development-cli new rule mandatory-tags -s warning -m "tags are mandatory"

  $ ruleset-development-cli new rule mandatory-tags -l /development/my-ruleset-project

ruleset-development-cli plugins

List installed plugins.

USAGE
  $ ruleset-development-cli plugins [--core]

FLAGS
  --core  Show core plugins.

DESCRIPTION
  List installed plugins.

EXAMPLES
  $ ruleset-development-cli plugins

See code: @oclif/plugin-plugins

ruleset-development-cli plugins:install PLUGIN...

Installs a plugin into the CLI.

USAGE
  $ ruleset-development-cli plugins:install PLUGIN...

ARGUMENTS
  PLUGIN  Plugin to install.

FLAGS
  -f, --force    Run yarn install with force flag.
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Installs a plugin into the CLI.
  Can be installed from npm or a git url.

  Installation of a user-installed plugin will override a core plugin.

  e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
  will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
  the CLI without the need to patch and update the whole CLI.


ALIASES
  $ ruleset-development-cli plugins add

EXAMPLES
  $ ruleset-development-cli plugins:install myplugin 

  $ ruleset-development-cli plugins:install https://github.com/someuser/someplugin

  $ ruleset-development-cli plugins:install someuser/someplugin

ruleset-development-cli plugins:inspect PLUGIN...

Displays installation properties of a plugin.

USAGE
  $ ruleset-development-cli plugins:inspect PLUGIN...

ARGUMENTS
  PLUGIN  [default: .] Plugin to inspect.

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Displays installation properties of a plugin.

EXAMPLES
  $ ruleset-development-cli plugins:inspect myplugin

ruleset-development-cli plugins:install PLUGIN...

Installs a plugin into the CLI.

USAGE
  $ ruleset-development-cli plugins:install PLUGIN...

ARGUMENTS
  PLUGIN  Plugin to install.

FLAGS
  -f, --force    Run yarn install with force flag.
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Installs a plugin into the CLI.
  Can be installed from npm or a git url.

  Installation of a user-installed plugin will override a core plugin.

  e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
  will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
  the CLI without the need to patch and update the whole CLI.


ALIASES
  $ ruleset-development-cli plugins add

EXAMPLES
  $ ruleset-development-cli plugins:install myplugin 

  $ ruleset-development-cli plugins:install https://github.com/someuser/someplugin

  $ ruleset-development-cli plugins:install someuser/someplugin

ruleset-development-cli plugins:link PLUGIN

Links a plugin into the CLI for development.

USAGE
  $ ruleset-development-cli plugins:link PLUGIN

ARGUMENTS
  PATH  [default: .] path to plugin

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Links a plugin into the CLI for development.
  Installation of a linked plugin will override a user-installed or core plugin.

  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
  command will override the user-installed or core plugin implementation. This is useful for development work.


EXAMPLES
  $ ruleset-development-cli plugins:link myplugin

ruleset-development-cli plugins:uninstall PLUGIN...

Removes a plugin from the CLI.

USAGE
  $ ruleset-development-cli plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ ruleset-development-cli plugins unlink
  $ ruleset-development-cli plugins remove

ruleset-development-cli plugins:uninstall PLUGIN...

Removes a plugin from the CLI.

USAGE
  $ ruleset-development-cli plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ ruleset-development-cli plugins unlink
  $ ruleset-development-cli plugins remove

ruleset-development-cli plugins:uninstall PLUGIN...

Removes a plugin from the CLI.

USAGE
  $ ruleset-development-cli plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ ruleset-development-cli plugins unlink
  $ ruleset-development-cli plugins remove

ruleset-development-cli plugins update

Update installed plugins.

USAGE
  $ ruleset-development-cli plugins update [-h] [-v]

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Update installed plugins.

ruleset-development-cli test

Lints the rules syntax and test all the rule examples

USAGE
  $ ruleset-development-cli test [-l <value>] [-f <value>] [-d] [-s]

FLAGS
  -d, --debug             generates debug output for the example being tested
  -f, --filter=<value>    regex used to filter the examples that are going to be validated
  -l, --location=<value>  path where the project has been created
  -s, --skipLinting       does not lint the rulesets before running the tests

DESCRIPTION
  Lints the rules syntax and test all the rule examples

EXAMPLES
  $ ruleset-development-cli test

  $ ruleset-development-cli test -f positive.*

  $ ruleset-development-cli test -f rule-34 --debug

  $ ruleset-development-cli test --debug

  $ ruleset-development-cli test --skipLinting

  $ ruleset-development-cli test -l /development/my-ruleset-project

See code: dist/commands/test.ts

ruleset-development-cli trace RULENAME ID

describe the command here

USAGE
  $ ruleset-development-cli trace [RULENAME] [ID] [-l <value>] [-a] [-n]

ARGUMENTS
  RULENAME  name of the rule where the example will be added
  ID        id of the example

FLAGS
  -a, --aggregate         aggregate failures from multiple proofs for the same node
  -l, --location=<value>  path where the project will be created
  -n, --negate            checks the negation of the rule, useful to check rules that should not conform

DESCRIPTION
  describe the command here

EXAMPLES
  $ ruleset-development-cli trace mandatory-tags negative1

  $ ruleset-development-cli trace mandatory-tags negative1 --agregate

  $ ruleset-development-cli trace mandatory-tags negative1 --negate

See code: dist/commands/trace.ts

ruleset-development-cli tutorial

Opens the AMF Ruleset Tutorial in the default system browser

USAGE
  $ ruleset-development-cli tutorial

DESCRIPTION
  Opens the AMF Ruleset Tutorial in the default system browser

EXAMPLES
  $ ruleset-development-cli tutorial

See code: dist/commands/tutorial.ts