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:

``sh-session
$ ruleset-development-cli tutorial
`

Development flow

1. Create a new ruleset project using the ruleset-development-cli [ruleset-name] from the directory for the ruleset
2. Create a new rule to the project with description and the right severity level using the ruleset-development-cli new rule [rule-name] command
3. Add positive and negative examples in the target specification languages using the ruleset-development-cli new example [rule-name] [example-id] command
4. 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
5. Check all the positive and negative examples for the ruleset using the ruleset-development-cli test command
6. 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
7. 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


![oclif](https://oclif.io)
![Version](https://www.npmjs.com/package/@aml-org/ruleset-development-cli)


* Development flow
* Usage
* Commands



Usage



`sh-session
$ npm install -g @aml-org/ruleset-development-cli
$ ruleset-development-cli COMMAND
running command...
$ ruleset-development-cli (--version)
@aml-org/ruleset-development-cli/1.0.0-beta.58 linux-x64 node-v18.20.8
$ ruleset-development-cli --help [COMMAND]
USAGE
$ ruleset-development-cli COMMAND
...
`

Commands

* ruleset-development-cli build
* ruleset-development-cli clean
* [ruleset-development-cli help [COMMANDS]](#ruleset-development-cli-help-commands)
* ruleset-development-cli import
* ruleset-development-cli lint
* [ruleset-development-cli model dump [RULENAME] [ID]](#ruleset-development-cli-model-dump-rulename-id)
* ruleset-development-cli model inspect RULENAME ID
* ruleset-development-cli new NAME
* 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 ]

FLAGS
-l, --location= path where the project will be 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: src/commands/build.ts_

ruleset-development-cli clean

cleans debug and model data

`
USAGE
$ ruleset-development-cli clean [-l ]

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

DESCRIPTION
cleans debug and model data

EXAMPLES
$ ruleset-development-cli clean

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

_See code: src/commands/clean.ts_

ruleset-development-cli help [COMMANDS]

Display help for ruleset-development-cli.

`
USAGE
$ ruleset-development-cli help [COMMANDS] [-n]

ARGUMENTS
COMMANDS 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 import

`
USAGE
$ ruleset-development-cli import [-l ] [-p ] [--omitExamples]

FLAGS
-l, --location= path where the project will be created
-p, --targetLocation= path where the ruleset should be imported as a project
--omitExamples omit scaffolding positive and negative examples for each rule
`

_See code: src/commands/import.ts_

ruleset-development-cli lint

Validates the rules syntax without testing any examples

`
USAGE
$ ruleset-development-cli lint [-l ]

FLAGS
-l, --location= path where the project will be 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: src/commands/lint.ts_

ruleset-development-cli model dump [RULENAME] [ID]

serializes the JSON-LD model for an example

`
USAGE
$ ruleset-development-cli model dump [RULENAME] [ID] [-l ] [-f ]

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

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

DESCRIPTION
serializes the JSON-LD model for an example

EXAMPLES
$ ruleset-development-cli model dump my-rule-1 example1negative
`

_See code: src/commands/model/dump.ts_

ruleset-development-cli model inspect RULENAME ID

toggles an interactive editor that shows the semantic model for a given input file

`
USAGE
$ ruleset-development-cli model inspect RULENAME ID [-l ]

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

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

DESCRIPTION
toggles an interactive editor that shows the semantic model for a given input file

EXAMPLES
$ ruleset-development-cli model inspect my-rule1 example1negative

$ ruleset-development-cli model inspect -f positive.*
`

_See code: src/commands/model/inspect.ts_

ruleset-development-cli new NAME

Generates a new ruleset project

`
USAGE
$ ruleset-development-cli new NAME [-l ] [-s
oas|swagger|raml|asyncapi|graphql|grpc|jsonld|gcl|agent-network|project] [-n ]

ARGUMENTS
NAME name of the ruleset

FLAGS
-l, --location= path where the project will be created
-n, --ruleFileName= name of the profile file in each rule
-s, --defaultSpec= 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: src/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 ] [-l ] [-o ]

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

FLAGS
-f, --format= [default: oas] spec format for the example (oas, swagger, raml, asyncapi, graphql, grpc, gcl,
project)
-l, --location= [default: .] path where the project has been created
-o, --only= 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
`

_See code: src/commands/new/example.ts_

ruleset-development-cli new rule NAME

creates a new rule for the ruleset

`
USAGE
$ ruleset-development-cli new rule NAME [-s warning|violation|info] [-m ] [-l ]

ARGUMENTS
NAME name of the rule

FLAGS
-l, --location= path where the project will be created
-m, --message= error message for the rule
-s, --severity= 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
`

_See code: src/commands/new/rule.ts_

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

GLOBAL FLAGS
--json Format output as json.

DESCRIPTION
Displays installation properties of a plugin.

EXAMPLES
$ ruleset-development-cli plugins:inspect myplugin
`

_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
`

_See code: @oclif/plugin-plugins_

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
`

_See code: @oclif/plugin-plugins_

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
`

_See code: @oclif/plugin-plugins_

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.
`

_See code: @oclif/plugin-plugins_

ruleset-development-cli test

Lints the rules syntax and tests all the rule examples

`
USAGE
$ ruleset-development-cli test [-l ] [-f ] [-d] [-s]

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

DESCRIPTION
Lints the rules syntax and tests 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: src/commands/test.ts_

ruleset-development-cli trace RULENAME ID

shows a trace report of all the failing rule constraints for an example

`
USAGE
$ ruleset-development-cli trace RULENAME ID [-l ] [-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= path where the project will be created
-n, --negate checks the negation of the rule, useful to check rules that should not conform

DESCRIPTION
shows a trace report of all the failing rule constraints for an example

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: src/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: src/commands/tutorial.ts_