Merge pull request #241 from DataDog/jacobotb/STAL-1373/config_schema

JSON Schema for the static analyzer configuration file.

.github/workflows/verify-schema.yaml

@@ -0,0 +1,11 @@
+on: push
+name: Check that the JSON schema for the configuration file matches the examples
+jobs:
+  integration_tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Use Node.js
+        uses: actions/setup-node@v1
+      - run: npm install -g pajv
+      - run: make -C schema

README.md

@@ -151,6 +151,22 @@ ignore-gitignore: false
 max-file-size-kb: 100
 ```
 
+## Configuration file schema
+
+There is a JSON Schema definition for the `static-analysis.datadog.yml` in the `schema` subdirectory.
+
+You can use it to check the syntax of your configuration file:
+
+1. Install https://www.npmjs.com/package/pajv (`npm install -g pajv`)
+2. Execute `pajv validate -s schema/schema.json -d path/to/your/static-analysis.datadog.yml`
+
+There are some examples of valid and invalid configuration files in the [`schema/examples/valid`](schema/examples/valid)
+and [`schema/examples/invalid`](schema/examples/invalid) subdirectories, respectively. If you make changes to the JSON
+Schema, you can test them against our examples:
+
+1. Install https://www.npmjs.com/package/pajv (`npm install -g pajv`)
+2. Execute `make -C schema`
+
 ## Other Tools
 
 ### datadog-export-rulesets

schema/Makefile

@@ -0,0 +1,14 @@
+all: test
+
+test: test-valid test-invalid
+
+INVALID_FILES=examples/invalid/*.yml
+VALID_FILES=examples/valid/*.yml
+
+test-valid:
+	pajv test -s schema.json -d "${VALID_FILES}" --valid
+
+test-invalid:
+	pajv test -s schema.json -d "${INVALID_FILES}" --invalid
+
+.PHONY: test test-valid test-invalid

schema/README.md

@@ -0,0 +1,16 @@
+# Schema for datadog-static-analyzer
+
+1. It validates what objects are required and valid
+2. Adding more properties in the schema is still making them valid
+3. Some validation may be missing but the core idea is present
+
+## How to test
+
+1. Install https://www.npmjs.com/package/pajv (`npm install -g pajv`)
+2. Invoke `make`
+
+
+## Configuration file examples
+
+ - [valid files here](examples/valid)
+ - [invalid files here](examples/invalid)

schema/examples/invalid/gitignore-wrong-type.yml

@@ -0,0 +1,6 @@
+rulesets:
+  - python-best-practices
+  - java-best-practices
+  - python-security
+# 'ignore-gitignore' is a boolean
+ignore-gitignore: 42

schema/examples/invalid/ignore-wrong-type.yml

@@ -0,0 +1,3 @@
+rulesets: [python-style]
+# 'ignore' must be a list.
+ignore: foo

schema/examples/invalid/maxfilesize-wrong-type.yml

@@ -0,0 +1,6 @@
+rulesets:
+  - python-best-practices
+  - java-best-practices
+  - python-security
+# 'max-file-size-kb' is a number
+max-file-size-kb: "100"

schema/examples/invalid/only-wrong-type.yml

@@ -0,0 +1,3 @@
+rulesets: [python-style]
+# 'only' must be a list.
+only: foo

schema/examples/invalid/rules-arguments-wrong-type-list.yml

@@ -0,0 +1,10 @@
+rulesets:
+  - java-best-practices:
+    rules:
+      avoid-printstacktrace:
+        # 'rulesets/rules/<rule>/arguments' is a map.
+        arguments:
+          - foo
+          - bar
+      loose-coupling:
+      one-declaration-per-line:

schema/examples/invalid/rules-arguments-wrong-type-map-of-list.yml

@@ -0,0 +1,10 @@
+rulesets:
+  - java-best-practices:
+    rules:
+      avoid-printstacktrace:
+        arguments:
+          # 'rulesets/rules/<rule>/arguments/<argument>' is a string or a map.
+          foo:
+            - bar
+      loose-coupling:
+      one-declaration-per-line:

schema/examples/invalid/rules-arguments-wrong-type-string.yml

@@ -0,0 +1,8 @@
+rulesets:
+  - java-best-practices:
+    rules:
+      avoid-printstacktrace:
+        # 'rulesets/rules/<rule>/arguments' is a map.
+        arguments: foo
+      loose-coupling:
+      one-declaration-per-line:

schema/examples/invalid/rules-ignore-wrong-type.yml

@@ -0,0 +1,8 @@
+rulesets:
+  - java-best-practices:
+    rules:
+      avoid-printstacktrace:
+        # 'rulesets/rules/<rule>/ignore' is a list.
+        ignore: foo
+      loose-coupling:
+      one-declaration-per-line:

schema/examples/invalid/rules-only-wrong-type.yml

@@ -0,0 +1,8 @@
+rulesets:
+  - java-best-practices:
+    rules:
+      avoid-printstacktrace:
+        # 'rulesets/rules/<rule>/ignore' is a list.
+        only: foo
+      loose-coupling:
+      one-declaration-per-line:

schema/examples/invalid/rules-wrong-type-list.yml

@@ -0,0 +1,7 @@
+rulesets:
+  - java-best-practices:
+    # 'rulesets/rules' is not a list.
+    rules:
+      - avoid-printstacktrace
+      - loose-coupling
+      - one-declaration-per-line

schema/examples/invalid/rules-wrong-type-string.yml

@@ -0,0 +1,4 @@
+rulesets:
+  - java-best-practices:
+    # 'rulesets/rules' is not a string
+    rules: avoid-printstacktrace

schema/examples/invalid/rulesets-absent.yml

@@ -0,0 +1,5 @@
+# 'rulesets' must be present.
+ignore:
+  - path1/path2
+only:
+  - path2/path3

schema/examples/invalid/rulesets-empty.yml

@@ -0,0 +1,6 @@
+# 'rulesets' must have elements.
+rulesets: [ ]
+ignore:
+  - path1/path2
+only:
+  - path2/path3

schema/examples/invalid/rulesets-ignore-wrong-type.yml

@@ -0,0 +1,4 @@
+rulesets:
+  - go-best-practices:
+    # 'rulesets/ignore' must be a list
+    ignore: bar

schema/examples/invalid/rulesets-indentation.yml

@@ -0,0 +1,6 @@
+rulesets:
+  # The configuration for each ruleset must be aligned below the ruleset's name.
+  - java-best-practices:
+      only: [foo]
+  - go-best-practices:
+      ignore: [bar]

schema/examples/invalid/rulesets-only-wrong-type.yml

@@ -0,0 +1,4 @@
+rulesets:
+  - java-best-practices:
+    # 'rulesets/only' must be a list
+    only: foo

schema/examples/invalid/rulesets-wrong-type-map.yml

@@ -0,0 +1,6 @@
+rulesets:
+  # 'rulesets' must be a list.
+  java-best-practices:
+    only: [foo]
+  go-best-practices:
+    ignore: [bar]

schema/examples/valid/arguments.yml

@@ -0,0 +1,16 @@
+rulesets:
+  - lorem_ipsum:
+    ignore:
+      - one/two
+    rules:
+      dolor:
+        ignore: [one/two]
+        only:
+          - one/two/three
+          - one/two/four
+        arguments:
+          sit_amet: "20"
+          consectetur:
+            /: 40
+            one/two/three/four: "80"
+            one/two/three/four/five: "160"

schema/examples/valid/complex1.yml

@@ -0,0 +1,12 @@
+rulesets:
+  - python-best-practices
+  - go-best-practices:
+  - java-best-practices:
+    rules:
+      avoid-printstacktrace:
+        only:
+          - "foo/bar"
+ignore:
+  - path1/path2
+only:
+  - path2/path3

schema/examples/valid/complex2.yml

@@ -0,0 +1,23 @@
+rulesets:
+  - python-best-practices
+  - java-best-practices:
+    rules:
+      avoid-printstacktrace:
+        only:
+          - "foo/bar"
+        arguments:
+          foo: "bar"
+          bar:
+            /: 42
+            uno/dos: "32"
+      loose-coupling:
+        arguments:
+          foo: bar
+      one-declaration-per-line:
+        ignore:
+          - "**"
+  - go-best-practices:
+ignore:
+  - path1/path2
+only:
+  - path2/path3

schema/examples/valid/extensions.yml

@@ -0,0 +1,21 @@
+# Additional fields not handled by the schema are accepted.
+# (Additional field names do NOT have to start with x-. This is done for tests only.)
+rulesets:
+  - java-best-practices:
+    x-ruleset-field: abc
+    ignore: [foo]
+    only: [bar]
+    rules:
+      avoid-printstacktrace:
+        x-rule-field: abc
+        only: [foo/bar]
+        ignore: [foo/baz]
+        arguments:
+          foo: "bar"
+  - go-best-practices:
+    x-other-ruleset-field: abc
+ignore:
+  - path1/path2
+only:
+  - path2/path3
+x-root-field: abc

schema/examples/valid/simple.yml

@@ -0,0 +1,4 @@
+rulesets:
+  - python-best-practices
+  - java-best-practices
+  - python-security

schema/examples/valid/with-gitignore.yml

@@ -0,0 +1,5 @@
+rulesets:
+  - python-best-practices
+  - java-best-practices
+  - python-security
+ignore-gitignore: false

schema/examples/valid/with-maxfilesize.yml

@@ -0,0 +1,5 @@
+rulesets:
+  - python-best-practices
+  - java-best-practices
+  - python-security
+max-file-size-kb: 100

schema/schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "rulesets": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          {
+            "$ref": "#/definitions/ruleset"
+          },
+          {
+            "$ref": "#/definitions/emptyRuleset"
+          },
+          {
+            "type": "string",
+            "minLength": 1
+          }
+        ]
+      },
+      "minItems": 1
+    },
+    "ignore": {
+      "$ref": "#/definitions/pathList"
+    },
+    "only": {
+      "$ref": "#/definitions/pathList"
+    },
+    "ignore-gitignore": {
+      "type": "boolean"
+    },
+    "max-file-size-kb": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "rulesets"
+  ],
+  "definitions": {
+    "rule": {
+      "type": "object",
+      "properties": {
+        "ignore": {
+          "$ref": "#/definitions/pathList"
+        },
+        "only": {
+          "$ref": "#/definitions/pathList"
+        },
+        "arguments": {
+          "type": "object",
+          "additionalProperties": {
+            "types": [
+              "string",
+              {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "emptyRuleset": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "null"
+      },
+      "minProperties": 1,
+      "maxProperties": 1
+    },
+    "ruleset": {
+      "type": "object",
+      "properties": {
+        "rules": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/rule "
+          }
+        },
+        "ignore": {
+          "$ref": "#/definitions/pathList"
+        },
+        "only": {
+          "$ref": "#/definitions/pathList"
+        }
+      },
+      "minProperties": 2
+    },
+    "pathList": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  }
+}
+
+