Migrating Csharp validator from AutoRest (#22)

Migrating Csharp validator from AutoRest

Author: dsgouda

.gitattributes

@@ -0,0 +1,63 @@
+###############################################################################
+# Set default behavior to automatically normalize line endings.
+###############################################################################
+* text=auto
+
+###############################################################################
+# Set default behavior for command prompt diff.
+#
+# This is need for earlier builds of msysgit that does not have it on by
+# default for csharp files.
+# Note: This is only used by command line
+###############################################################################
+#*.cs     diff=csharp
+
+###############################################################################
+# Set the merge driver for project and solution files
+#
+# Merging from the command prompt will add diff markers to the files if there
+# are conflicts (Merging from VS is not affected by the settings below, in VS
+# the diff markers are never inserted). Diff markers may cause the following 
+# file extensions to fail to load in VS. An alternative would be to treat
+# these files as binary and thus will always conflict and require user
+# intervention with every merge. To do so, just uncomment the entries below
+###############################################################################
+#*.sln       merge=binary
+#*.csproj    merge=binary
+#*.vbproj    merge=binary
+#*.vcxproj   merge=binary
+#*.vcproj    merge=binary
+#*.dbproj    merge=binary
+#*.fsproj    merge=binary
+#*.lsproj    merge=binary
+#*.wixproj   merge=binary
+#*.modelproj merge=binary
+#*.sqlproj   merge=binary
+#*.wwaproj   merge=binary
+
+###############################################################################
+# behavior for image files
+#
+# image files are treated as binary by default.
+###############################################################################
+#*.jpg   binary
+#*.png   binary
+#*.gif   binary
+
+###############################################################################
+# diff behavior for common document formats
+# 
+# Convert binary document formats to text before diffing them. This feature
+# is only available from the command line. Turn it on by uncommenting the 
+# entries below.
+###############################################################################
+#*.doc   diff=astextplain
+#*.DOC   diff=astextplain
+#*.docx  diff=astextplain
+#*.DOCX  diff=astextplain
+#*.dot   diff=astextplain
+#*.DOT   diff=astextplain
+#*.pdf   diff=astextplain
+#*.PDF   diff=astextplain
+#*.rtf   diff=astextplain
+#*.RTF   diff=astextplain

.gitignore

@@ -3,4 +3,14 @@ src/**/*.js
 src/**/*.d.ts
 node_modules/
 pack/
-*.tgz
+src/**/*.tgz
+
+# remove dotnet artifacts
+src/dotnet/**/[Bb]in/
+src/dotnet/**/[Oo]bj/
+src/dotnet/**/*.deps.json
+src/dotnet/**/[Dd]ebug*/
+src/dotnet/**/[Rr]elease/
+**/*.DotSettings.user
+# ignore vs
+**/.vs/

.npmignore

@@ -1,3 +1,3 @@
 node_modules/
 # Any logs
-.log
+.log

.travis.yml

@@ -3,5 +3,13 @@ dist: trusty
 language: node_js
 node_js:
   - "6.9.5"
+install:
+  # node packages
+  - npm install
+  # dotnet
+  - sudo sh -c 'echo "deb [arch=amd64] https://apt-mo.trafficmanager.net/repos/dotnet/ trusty main" > /etc/apt/sources.list.d/dotnetdev.list' 
+  - sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893
+  - sudo apt-get update
+  - sudo apt-get install dotnet-dev-1.0.0-rc4-004769 -y
 script:
   - gulp

.vscode/launch.json

@@ -8,7 +8,7 @@
             "cwd": "${workspaceRoot}",
             "program": "${workspaceRoot}/node_modules/mocha/bin/mocha",
             "args": [
-                "./src/azure-openapi-validator/tests/*.js",
+                "./src/typescript/azure-openapi-validator/tests/*.js",
                 "--colors"
             ],
             "outFiles": [],

README.md

@@ -10,22 +10,40 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 ## Build scripts
 ### How to build
 The first step would be to run ```npm install``` so we have all the required modules installed.
-
+#### How to build the whole repo
 ```
 gulp build
 ```
-This transpiles the typescript scripts into javascript files under the js folder.
+#### How to build the typescript repo
+```
+gulp build/typescript
+```
+#### How to build the dotnet repo
+To restore the dotnet packages
+```
+gulp restore/dotnet
+```
+This builds the dotnet projects.
+```
+gulp build/dotnet
+```
 ### How to test
+To run all tests under the repo
 ```
 gulp test
 ```
-This runs the tests under tests directory.
-
-### How to write a new validation rule
+#### How to run the typescript tests
+```
+gulp test/typescript
+```
+#### How to run the dotnet tests
+```
+gulp test/dotnet
+```
+### How to write a new validation rule using typescript
 1. Add a typescript file under ```azure-openapi-validator``` directory named same as the name of the rule. Add the ```id```, ```name```, ```severity```, ```category```,  ```mergeState```,  ```openapiType```,  ```appliesTo_JsonQuery``` properties to the rule. ```appliesTo_JsonQuery``` is the node(s) to which the rule needs to be applied. This is evaluated using JsonPaths. Please refer [here](https://www.npmjs.com/package/jsonpath#jsonpath-syntax) for a brief tutorial about JsonPaths.
-2. Next, implement the ```run``` method under the rule that actually does the validation. Add a reference to this script file under ```src\azure-openapi-validator\index.ts```.
-3. Lastly add a test case for the validation rule, by adding a test json/yaml under ```src\azure-openapi-validator\tests\resources``` and a script under ```src\azure-openapi-validator\tests``` depending on the type of the validation rule.
+2. Next, implement the ```run``` method under the rule that actually does the validation. Add a reference to this script file under ```src/typescript/azure-openapi-validator/index.ts```.
+3. Lastly add a test case for the validation rule, by adding a test json/yaml under ```src/typescript/azure-openapi-validator/tests/resources``` and a script under ```src/typescript/azure-openapi-validator/tests``` depending on the type of the validation rule.
 
-## Publishing the package
-Npm packages **MUST** be published from the `release` branch, `master` is promoted to release on a monthly cadence. All development **MUST** be done on the `master` branch. The package version of `master` branch **MUST** be incremented after every promotion to release.
+### How to publish
 

docs/anonymous-parameter-types.md

@@ -0,0 +1,60 @@
+# AnonymousParameterTypes
+## Description
+This rule appears when you define a model type inline, rather than in the `definitions` section. Since code generation does not have a name to call your model, the class will have a non-descriptive name. Additionally, if it represents the same type as another parameter in a different operation, then it becomes impossible to reuse that same class for both operations.
+## How to fix
+Move the schema to the `definitions` section and reference it using `$ref`.
+## Effect on generated code
+### Before
+#### Spec
+```json5
+…
+"parameters": [
+    {
+        "name": "foo",
+        "in": "body",
+        "schema": {
+            "type": "object",
+            "properties": {
+                …
+            }
+        }
+    }
+]
+…
+```
+#### Generated code
+```csharp
+public class FooParameter1 {
+    …
+}
+```
+### After
+#### Spec
+```json5
+…
+"parameters": [
+    {
+        "name": "foo",
+        "in": "body",
+        "schema": {
+            "$ref": "#/definition/FooCreationSettings"
+        }
+    }
+],
+…
+"definitions": {
+    "FooCreationSettings": {
+        "type": "object",
+        "properties": {
+            …
+        }
+    }
+}
+…
+```
+#### Generated code
+```csharp
+public class FooCreationSettings {
+    …
+}
+```

docs/avoid-nested-properties.md

@@ -0,0 +1,65 @@
+# AvoidNestedProperties
+## Description
+This rule appears when you define a property with the name `properties`, and do not use the [`x-ms-client-flatten` extension](../../extensions/readme.md#x-ms-client-flatten). Users often provide feedback that they don't want to create multiple levels of properties to be able to use an operation. By applying the `x-ms-client-flatten` extension, you move the inner `properties` to the top level of your definition.
+## How to fix
+Add the `x-ms-client-flatten` extension to the inner `properties` definition.
+## Effect on generated code
+### Before
+#### Spec
+```json5
+…
+"definitions": {
+    "Foo": {
+        "type": "object",
+        "properties": {
+            "properties": {
+                "type": "object",
+                "properties": {
+                    "bar": {
+                        "type": "string"
+                    }
+                }
+            }
+        }
+    }
+}
+…
+```
+#### Generated code
+```csharp
+public class Foo {
+    FooProperties Properties { get; set; } 
+}
+
+public class FooProperties {
+    string Bar { get; set; } 
+}
+```
+### After
+#### Spec
+```json5
+…
+"definitions": {
+    "Foo": {
+        "type": "object",
+        "properties": {
+            "properties": {
+                "type": "object",
+                "properties": {
+                    "bar": {
+                        "type": "string"
+                    }
+                }
+            },
+            "x-ms-client-flatten": true
+        }
+    }
+}
+…
+```
+#### Generated code
+```csharp
+public class Foo {
+    string Bar { get; set; } 
+}
+```

docs/boolean-property.md

@@ -0,0 +1,13 @@
+# M3018 - BooleanPropertyNotRecommended
+## Description
+Booleans are not descriptive and make them hard to use. Instead use string enums with allowed set of values defined.
+
+## Why?
+This is a warning prompting to evaluate whether the property is really a boolean or not, the intent is to consider if there could be more than 2 values possible for the property in the future or not. If the answer is no, then a boolean is fine, if the answer is yes, there could be other values added in the future, making it an enum can help avoid breaking changes in the SDKs in the future.
+  
+## How to fix
+Create an enum property, follow autorest [x-ms-enum extension guidelines](https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-enum)
+
+
+## Impact on generated code
+Boolean property will turn into a String or an Enum (if SDK language supports it), this will depend on "modelAsString" property values as specified in [x-ms-enum extension guidelines](https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-enum)

docs/camel-casing-validation-rules.md

@@ -0,0 +1,58 @@
+#M3016 - DefinitionsPropertiesNamesCamelCase/BodyPropertiesNamesCamelCase
+## Description
+This violation is flagged if a model definition's property name (DefinitionsPropertiesNamesCamelCase) or a request body parameter's property name (BodyPropertiesNamesCamelCase)  is not in `camelCase` format. This is because the model's properties are sent across the wire and must adhere to common Json conventions for naming. This implies that every property name must start with a lower cased letter and all subsequent words within the name must start with a capital letter. In cases where there are acronyms involved, a maximum of three contiguous capital letters are allowed (acronyms should not be longer that 2 characters - see https://msdn.microsoft.com/en-us/library/141e06ef(v=vs.71).aspx, third upper case could be start of next word). Eg: `redisCache`, `publicIPAddress`, `location` are valid, but `sampleSQLQuery` is not (must be renamed as `sampleSqlQuery`).
+
+## How to fix
+Convert the property name string into `camelCase` format as suggested in the description
+
+
+## Effect on generated code
+### Before
+#### Spec
+```json5
+…
+"ModelDefinition":{
+    "properties":{
+        "ModelProperty1":{
+            "type":"string"
+        }
+    }
+}
+…
+```
+#### Generated code
+```csharp
+public class FooParameter1 {
+    …
+}
+```
+### After
+#### Spec
+```json5
+…
+"parameters": [
+    {
+        "name": "foo",
+        "in": "body",
+        "schema": {
+            "$ref": "#/definition/FooCreationSettings"
+        }
+    }
+],
+…
+"definitions": {
+    "FooCreationSettings": {
+        "type": "object",
+        "properties": {
+            …
+        }
+    }
+}
+…
+```
+#### Generated code
+```csharp
+public class FooCreationSettings {
+    …
+}
+```

docs/default-in-enum.md

@@ -0,0 +1,11 @@
+# DefaultInEnum
+## Description
+This rule applies when the value specified by the `default` property does not appear in the `enum` constraint for a schema.
+## How to fix
+Add the value from `default` property to the set of values in the `enum` constraint.
+
+_or_
+
+Change the value for the `default` property to one of the values in the `enum` array.
+## Effect on generated code
+Failing to pass this validation rule affects the generated code because default values allow users to call an operation without specifying a value for that parameter or property. In that case, the generated code will send the default value instead, which should be invalid for the server. Spec files that have this issue generate code that can easily send bad requests.

docs/descriptive-description-required.md

@@ -0,0 +1,14 @@
+# DescriptiveDescriptionRequired
+## Description
+This rule validates that a description property is not empty. An empty description does not provide value for customers and makes it more difficult to use the generated code as a consumer.
+## How to fix
+Replace the empty string with a useful description.
+## Effect on generated code
+### Before
+```
+
+```
+### After
+```
+
+```