diff --git a/docs/rules-development-guide/master.adoc b/docs/rules-development-guide/master.adoc index 559d4df6..6af54249 100644 --- a/docs/rules-development-guide/master.adoc +++ b/docs/rules-development-guide/master.adoc @@ -102,6 +102,12 @@ include::topics/running-analysis-using-custom-yaml-rule.adoc[leveloffset=+3] // Create Your First YAML Rule include::topics/create-first-yaml-rule.adoc[leveloffset=+2] +include::topics/create-go-custom-rule.adoc[leveloffset=+2] + +include::topics/create-python-custom-rule.adoc[leveloffset=+2] + +include::topics/create-nodejs-custom-rule.adoc[leveloffset=+2] + // removing section subject to a later re-write // Testing XML Rules // include::topics/testing-rules.adoc[leveloffset=+1] diff --git a/docs/topics/create-go-custom-rule.adoc b/docs/topics/create-go-custom-rule.adoc new file mode 100644 index 00000000..0c2646a4 --- /dev/null +++ b/docs/topics/create-go-custom-rule.adoc @@ -0,0 +1,69 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: PROCEDURE +[id="create-go-custom-rule_{context}"] += Creating a custom Go rule + +[role="_abstract"] +You can create custom rules for Golang (Go) applications based on the following example. + +You can use the following custom rule to check if {ProductShortName} triggers an incident when it detects a `go` file in your project. + +.Procedure +. Create a `go-rule-001.yml` file in a directory. + +. Copy the following rule in the `yaml` file: ++ + +[source, yaml] +---- +- message: golang apiextensions/v1/customresourcedefinitions found + description: "golang apiextensions/v1/customresourcedefinitions found" + ruleID: go-lang-ref-001 + effort: 1 + when: + go.referenced: + pattern: "v1beta1.CustomResourceDefinition" +---- + +. Create a test `go` file named *example.go* in your `Home` directory. + +. Paste the following code in the *example.go* file: ++ + +[source, go] +---- +package main + +import ( + "fmt" + + "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1" +) + +func main() { + fmt.Println(v1beta1.CustomResourceDefinition{}) + +} +---- + +. Run the following command in the {ProductShortName} CLI: ++ + +[source, terminal] +---- +$ ./mta-cli analyze -i __ -o __ \ --run-local=false --rules __ +---- ++ + +[NOTE] +==== +Add the `--overwrite` option if you want to use the same directory for the report when you run subsequent tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you run. +==== + +. Open the static report at `/home//output/static-report/` in your browser. + +. Navigate to the issues to verify the `golang apiextensions/v1/customresourcedefinitions found {{file}}:{{lineNumber}}` issue. + diff --git a/docs/topics/create-nodejs-custom-rule.adoc b/docs/topics/create-nodejs-custom-rule.adoc new file mode 100644 index 00000000..4e503f93 --- /dev/null +++ b/docs/topics/create-nodejs-custom-rule.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: PROCEDURE +[id="create-nodejs-custom-rule_{context}"] += Creating a custom Node.js rule + +[role="_abstract"] + You must create custom rules to analyze `Node.js` applications by using {ProductShortName}. A `Node.js` rule can contain `nodejs.referenced` capability which supports the `pattern` field. + +The following example uses a custom rule to check if a `.tsx` file in the `Node.js` project imports the `React` framework. + +.Procedure +. Create the `test-nodejs` directory. ++ + +[source, terminal] +---- +$ mkdir -p ~/test-nodejs +---- + +. Save the following rule as `nodejs-rule-001.yml` in the `test-nodejs` directory: ++ +[source, yaml] +---- +- ruleID: test-tsx-support-00000 + description: Found React import in .tsx file + message: Found React import in .tsx file + effort: 1 + when: + nodejs.referenced: + pattern: "React" +---- + +. Create the following test application in the `Component.tsx` file: ++ + +[source, node.js] +---- +import React from 'react'; + export const MyComponent: React.FC = () =>
Hello
; +---- + +. Run the following command in the {ProductShortName} CLI: ++ + +[source, terminal] +---- +$ ./mta-cli analyze -i ~/test-nodejs/ -o \ +~/test-nodejs/report --run-local=false \ +--rules ~/test-nodejs/nodejs-rule-001.yml +---- ++ + +[NOTE] +==== +Add the `--overwrite` option if you want to use the same directory for the report when you run subsequent tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you run. +==== + +. Open the static report at `~/test-nodejs/report/static-report/index.html` in your browser. + +. Click the __ to open the Dashboard. + +. Review the incidents in the *Issues* tab. + diff --git a/docs/topics/create-python-custom-rule.adoc b/docs/topics/create-python-custom-rule.adoc new file mode 100644 index 00000000..ae1d0b4d --- /dev/null +++ b/docs/topics/create-python-custom-rule.adoc @@ -0,0 +1,94 @@ +// Module included in the following assemblies: +// +// * docs/rules-development-guide/master.adoc + +:_mod-docs-content-type: PROCEDURE +[id="create-python-custom-rule_{context}"] += Creating custom Python rules + +[role="_abstract"] +You must create custom rules to analyze `Python` applications by using {ProductShortName}. A `Python` rule can contain `python.referenced` capability with the supported fields. + +The following example uses two custom rules: + +* The first rule checks if `bad_method` is specified +* The second rule checks if `hello_world` is specified in `file_a.py` in your project. + +.Procedure +. Create the directory `test-python`. ++ +[source, terminal] +---- +$ mkdir -p ~/test-python +---- + +. Create a `python-rule-001.yml` file in the directory and add the following rule: ++ +[source, yaml] +---- +- category: mandatory + ruleID: python-rule-001 + effort: 1 + description: "Bad method" + when: + python.referenced: + pattern: "bad_method" +---- + +. Create a `python-rule-002.yml` file in the directory and add the following rule: ++ +[source, yaml] +---- + - category: mandatory + ruleID: python-rule-002 + effort: 1 + message: "Found a python" + when: + python.referenced: + pattern: "hello_world" +---- + +. Save the following `Python` code as `file_b.py`. ++ + +[source, python] +---- +import deprecated +def hello_world(): + return "Hello, world!" +@deprecated.deprecated("This method is bad!") +def bad_method(): + return "I'm a bad method!" +---- + +. Save the following code as a second file, `file_a.py`. ++ +[source, python] +---- +import file_b +print(file_b.hello_world()) +print(file_b.bad_method()) +---- + +. Run the following command in the {ProductShortName} CLI: ++ +[source, terminal] +---- +$ ./mta-cli analyze -i ~/test-python/ -o \ +~/test-python/report --run-local=false \ +--rules ~/test-python/python-rule-001. \ +--rules ~/test-python/python-rule-002.yml +---- ++ + +[NOTE] +==== +Add the `--overwrite` option if you want to use the same directory for the report when you run subsequent tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you run. +==== + +. Open the static report at `~/test-python/report/static-report/index.html` in your browser. + +. Click the __ to open the Dashboard. + +. Review the incidents in the *Issues* tab. +