Refactored Perks, with Help, other refinements (#2708)

* ready to integrate help

* test case

* help settings and rendering

* boilerplate

* decl

* more stable commonmark stage

* remodel help

* blaming ext. reference bug fix

* help pipeline

* updated perks packgaes

* padEnd polyfill, plugin refactoring, core help plugins

* cleanup

* dashdash

* yargs goodbye

* regen

* regen

* regenerated

Samples/1a-code-generation-minimal/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/1b-code-generation-multilang/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/1c-multiple-input-swaggers/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/1d-common-settings/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/1e-help/readme.md

@@ -0,0 +1,33 @@
+# Scenario: Query command line help
+
+> see https://aka.ms/autorest
+
+There is generic help and help specific to plugins, which will actually be queried from extensions on the fly.
+This allows extensions that we don't even know about to not only be usable but also discoverable through AutoRest.
+
+``` yaml
+help: true # we wanna query for help in each of the following scenarios
+
+batch:
+  # no additional arguments => query for generic AutoRest help
+  - {}
+  # plugin specific help (on CLI you would say something like `autorest --help --csharp`)
+  - csharp: true
+  - azure-validator: true
+  - csharp: true
+    azure-arm: true # could provide customized help for this!
+    fluent: true
+  # combination (let's list everything *we* own to make sure it works)
+  - azureresourceschema: true
+    csharp: true
+    go: true
+    java: true
+    nodejs: true
+    php: true
+    python: true
+    ruby: true
+    typescript: true
+    azure-validator: true
+    model-validator: true
+    semantic-validator: true
+```

Samples/1e-help/shell/code.txt

@@ -0,0 +1 @@
+0

Samples/1e-help/shell/stderr.txt

@@ -0,0 +1 @@
+

Samples/1e-help/shell/stdout.txt

@@ -0,0 +1,208 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+   More specific help is shown when combining the following switches with --help .
+   More specific help is shown when combining the following switches with --help .
+   More specific help is shown when combining the following switches with --help .
+   More specific help is shown when combining the following switches with --help .
+   More specific help is shown when combining the following switches with --help .
+   we officially support and maintain the following functionality.
+   we officially support and maintain the following functionality.
+   we officially support and maintain the following functionality.
+   we officially support and maintain the following functionality.
+   we officially support and maintain the following functionality.
+   While AutoRest can be extended arbitrarily by 3rd parties (say, with a custom generator),
+   While AutoRest can be extended arbitrarily by 3rd parties (say, with a custom generator),
+   While AutoRest can be extended arbitrarily by 3rd parties (say, with a custom generator),
+   While AutoRest can be extended arbitrarily by 3rd parties (say, with a custom generator),
+   While AutoRest can be extended arbitrarily by 3rd parties (say, with a custom generator),
+  --azure-validator             validates an OpenAPI document against guidelines to improve quality (and optionally Azure guidelines)
+  --azure-validator             validates an OpenAPI document against guidelines to improve quality (and optionally Azure guidelines)
+  --azure-validator             validates an OpenAPI document against guidelines to improve quality (and optionally Azure guidelines)
+  --azure-validator             validates an OpenAPI document against guidelines to improve quality (and optionally Azure guidelines)
+  --azure-validator             validates an OpenAPI document against guidelines to improve quality (and optionally Azure guidelines)
+  --azureresourceschema         generate Azure resource schemas
+  --azureresourceschema         generate Azure resource schemas
+  --azureresourceschema         generate Azure resource schemas
+  --azureresourceschema         generate Azure resource schemas
+  --azureresourceschema         generate Azure resource schemas
+  --base-folder                 path to resolve relative paths (input/output files/folders) against; default: directory of configuration file, current directory otherwise
+  --base-folder                 path to resolve relative paths (input/output files/folders) against; default: directory of configuration file, current directory otherwise
+  --base-folder                 path to resolve relative paths (input/output files/folders) against; default: directory of configuration file, current directory otherwise
+  --base-folder                 path to resolve relative paths (input/output files/folders) against; default: directory of configuration file, current directory otherwise
+  --base-folder                 path to resolve relative paths (input/output files/folders) against; default: directory of configuration file, current directory otherwise
+  --csharp                      generate C# client code
+  --csharp                      generate C# client code
+  --csharp                      generate C# client code
+  --csharp                      generate C# client code
+  --csharp                      generate C# client code
+  --debug                       display debug logging information
+  --debug                       display debug logging information
+  --debug                       display debug logging information
+  --debug                       display debug logging information
+  --debug                       display debug logging information
+  --force                       force the re-installation of the autorest-core extension and frameworks
+  --force                       force the re-installation of the autorest-core extension and frameworks
+  --force                       force the re-installation of the autorest-core extension and frameworks
+  --force                       force the re-installation of the autorest-core extension and frameworks
+  --force                       force the re-installation of the autorest-core extension and frameworks
+  --go                          generate Go client code
+  --go                          generate Go client code
+  --go                          generate Go client code
+  --go                          generate Go client code
+  --go                          generate Go client code
+  --help                        display help (combine with flags like --csharp to get further details about specific functionality)
+  --help                        display help (combine with flags like --csharp to get further details about specific functionality)
+  --help                        display help (combine with flags like --csharp to get further details about specific functionality)
+  --help                        display help (combine with flags like --csharp to get further details about specific functionality)
+  --help                        display help (combine with flags like --csharp to get further details about specific functionality)
+  --info                        display information about the installed version of autorest and its extensions
+  --info                        display information about the installed version of autorest and its extensions
+  --info                        display information about the installed version of autorest and its extensions
+  --info                        display information about the installed version of autorest and its extensions
+  --info                        display information about the installed version of autorest and its extensions
+  --input-file=<string | string[]>  OpenAPI file to use as input (use this setting repeatedly to pass multiple filesat ...
+  --input-file=<string | string[]>  OpenAPI file to use as input (use this setting repeatedly to pass multiple filesat ...
+  --input-file=<string | string[]>  OpenAPI file to use as input (use this setting repeatedly to pass multiple filesat ...
+  --input-file=<string | string[]>  OpenAPI file to use as input (use this setting repeatedly to pass multiple filesat ...
+  --input-file=<string | string[]>  OpenAPI file to use as input (use this setting repeatedly to pass multiple filesat ...
+  --java                        generate Java client code
+  --java                        generate Java client code
+  --java                        generate Java client code
+  --java                        generate Java client code
+  --java                        generate Java client code
+  --latest                      installs the latest autorest-core extension
+  --latest                      installs the latest autorest-core extension
+  --latest                      installs the latest autorest-core extension
+  --latest                      installs the latest autorest-core extension
+  --latest                      installs the latest autorest-core extension
+  --list-available              display available AutoRest versions
+  --list-available              display available AutoRest versions
+  --list-available              display available AutoRest versions
+  --list-available              display available AutoRest versions
+  --list-available              display available AutoRest versions
+  --message-format=<"regular" | "json">  format of messages (e.g. from OpenAPI validation); default: "regular"
+  --message-format=<"regular" | "json">  format of messages (e.g. from OpenAPI validation); default: "regular"
+  --message-format=<"regular" | "json">  format of messages (e.g. from OpenAPI validation); default: "regular"
+  --message-format=<"regular" | "json">  format of messages (e.g. from OpenAPI validation); default: "regular"
+  --message-format=<"regular" | "json">  format of messages (e.g. from OpenAPI validation); default: "regular"
+  --model-validator             validates an OpenAPI document against linked examples (see https://github.com/Azure/azure-rest-api-specs/search?q=x-ms-examples )
+  --model-validator             validates an OpenAPI document against linked examples (see https://github.com/Azure/azure-rest-api-specs/search?q=x-ms-examples )
+  --model-validator             validates an OpenAPI document against linked examples (see https://github.com/Azure/azure-rest-api-specs/search?q=x-ms-examples )
+  --model-validator             validates an OpenAPI document against linked examples (see https://github.com/Azure/azure-rest-api-specs/search?q=x-ms-examples )
+  --model-validator             validates an OpenAPI document against linked examples (see https://github.com/Azure/azure-rest-api-specs/search?q=x-ms-examples )
+  --nodejs                      generate NodeJS client code
+  --nodejs                      generate NodeJS client code
+  --nodejs                      generate NodeJS client code
+  --nodejs                      generate NodeJS client code
+  --nodejs                      generate NodeJS client code
+  --php                         generate PHP client code
+  --php                         generate PHP client code
+  --php                         generate PHP client code
+  --php                         generate PHP client code
+  --php                         generate PHP client code
+  --preview                     enables using autorest extensions that are not yet released
+  --preview                     enables using autorest extensions that are not yet released
+  --preview                     enables using autorest extensions that are not yet released
+  --preview                     enables using autorest extensions that are not yet released
+  --preview                     enables using autorest extensions that are not yet released
+  --python                      generate Python client code
+  --python                      generate Python client code
+  --python                      generate Python client code
+  --python                      generate Python client code
+  --python                      generate Python client code
+  --reset                       removes all autorest extensions and downloads the latest version of the autorest-core extension
+  --reset                       removes all autorest extensions and downloads the latest version of the autorest-core extension
+  --reset                       removes all autorest extensions and downloads the latest version of the autorest-core extension
+  --reset                       removes all autorest extensions and downloads the latest version of the autorest-core extension
+  --reset                       removes all autorest extensions and downloads the latest version of the autorest-core extension
+  --ruby                        generate Ruby client code
+  --ruby                        generate Ruby client code
+  --ruby                        generate Ruby client code
+  --ruby                        generate Ruby client code
+  --ruby                        generate Ruby client code
+  --typescript                  generate TypeScript client code
+  --typescript                  generate TypeScript client code
+  --typescript                  generate TypeScript client code
+  --typescript                  generate TypeScript client code
+  --typescript                  generate TypeScript client code
+  --verbose                     display verbose logging information
+  --verbose                     display verbose logging information
+  --verbose                     display verbose logging information
+  --verbose                     display verbose logging information
+  --verbose                     display verbose logging information
+  --version=<string>            use the specified version of the autorest-core extension
+  --version=<string>            use the specified version of the autorest-core extension
+  --version=<string>            use the specified version of the autorest-core extension
+  --version=<string>            use the specified version of the autorest-core extension
+  --version=<string>            use the specified version of the autorest-core extension
+  See: https://aka.ms/autorest/cli for additional documentation
+--output-folder=<string>      target folder for generated artifacts; default: "<base folder>/generated"
+--output-folder=<string>      target folder for generated artifacts; default: "<base folder>/generated"
+--output-folder=<string>      target folder for generated artifacts; default: "<base folder>/generated"
+--output-folder=<string>      target folder for generated artifacts; default: "<base folder>/generated"
+--output-folder=<string>      target folder for generated artifacts; default: "<base folder>/generated"
+(C) 2017 Microsoft Corporation.
+AutoRest code generation utility [version: 2.0.0]
+Core Functionality
+Core Functionality
+Core Functionality
+Core Functionality
+Core Functionality
+Core Settings and Switches
+Core Settings and Switches
+Core Settings and Switches
+Core Settings and Switches
+Core Settings and Switches
+https://aka.ms/autorest
+Manage Installation
+Manage Installation
+Manage Installation
+Manage Installation
+Manage Installation
+Overall Verbosity
+Overall Verbosity
+Overall Verbosity
+Overall Verbosity
+Overall Verbosity
+Usage: autorest [configuration-file.md] [...options]

Samples/2a-validation/shell/stderr.txt

@@ -1,3 +1,14 @@
+
+
+
+
+
+
+
+
+
+
+
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:126:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].delete)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:165:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].get)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:204:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].patch)

Samples/2a-validation/shell/stdout.txt

@@ -1,8 +1,23 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:14:4 ($.consumes[1])
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:18:4 ($.produces[1])
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:254:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/listKeys"].post)
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:358:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/regenerateKey"].post)
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:40:6 ($.paths["/subscriptions/{subscriptionId}/providers/Microsoft.Storage/checkNameAvailability"].post)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:412:8 ($.paths["/subscriptions/{subscriptionId}/providers/Microsoft.Storage/usages"].get.operationId)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:437:4 ($.definitions.StorageAccountCheckNameAvailabilityParameters)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:439:8 ($.definitions.StorageAccountCheckNameAvailabilityParameters.properties.name)
@@ -19,8 +34,8 @@
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:726:8 ($.definitions.StorageAccountRegenerateKeyParameters.properties.keyName)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:74:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].put)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:800:4 ($.definitions.Resource)
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 WARNING (DescriptionAndTitleMissing/R4000/SDKViolation): 'keyName' model/property lacks 'description' and 'title' property. Consider adding a 'description'/'title' element. Accurate description/title is essential for maintaining reference documentation.
 WARNING (DescriptionAndTitleMissing/R4000/SDKViolation): 'name' model/property lacks 'description' and 'title' property. Consider adding a 'description'/'title' element. Accurate description/title is essential for maintaining reference documentation.
@@ -39,7 +54,4 @@ WARNING (EnumInsteadOfBoolean/R3018/RPCViolation): Booleans are not descriptive
 WARNING (NonApplicationJsonType/R2004/RPCViolation): Only 'application/json' content-type is supported by ARM.
 WARNING (NonApplicationJsonType/R2004/RPCViolation): Only 'application/json' content-type is supported by ARM.
 WARNING (OperationIdNounConflictingModelNames/R2063/SDKViolation): OperationId has a noun that conflicts with one of the model names in definitions section. The model name will be disambiguated to 'UsageModel'. Consider using the plural form of 'Usage' to avoid this. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change.
-WARNING (PostOperationIdContainsUrlVerb/R2066/SDKViolation): OperationId should contain the verb: '/subscriptions/{subscriptionid}/providers/microsoft.storage/checknameavailability' in:'StorageAccounts_CheckNameAvailability'. Consider updating the operationId
-WARNING (PostOperationIdContainsUrlVerb/R2066/SDKViolation): OperationId should contain the verb: '/subscriptions/{subscriptionid}/resourcegroups/{resourcegroupname}/providers/microsoft.storage/storageaccounts/{accountname}/listkeys' in:'StorageAccounts_ListKeys'. Consider updating the operationId
-WARNING (PostOperationIdContainsUrlVerb/R2066/SDKViolation): OperationId should contain the verb: '/subscriptions/{subscriptionid}/resourcegroups/{resourcegroupname}/providers/microsoft.storage/storageaccounts/{accountname}/regeneratekey' in:'StorageAccounts_RegenerateKey'. Consider updating the operationId
 WARNING (PutRequestResponseScheme/R2017/SDKViolation): A PUT operation request body schema should be the same as its 200 response schema, to allow reusing the same entity between GET and PUT. If the schema of the PUT request body is a superset of the GET response body, make sure you have a PATCH operation to make the resource updatable. Operation: 'StorageAccounts_Create' Request Model: 'StorageAccountCreateParameters' Response Model: 'StorageAccount'

Samples/2b-suppressions/shell/stderr.txt

@@ -1,3 +1,14 @@
+
+
+
+
+
+
+
+
+
+
+
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:126:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].delete)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:165:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].get)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:204:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].patch)

Samples/2b-suppressions/shell/stdout.txt

@@ -1,8 +1,23 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:14:4 ($.consumes[1])
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:18:4 ($.produces[1])
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:254:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/listKeys"].post)
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:358:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/regenerateKey"].post)
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:40:6 ($.paths["/subscriptions/{subscriptionId}/providers/Microsoft.Storage/checkNameAvailability"].post)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:412:8 ($.paths["/subscriptions/{subscriptionId}/providers/Microsoft.Storage/usages"].get.operationId)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:437:4 ($.definitions.StorageAccountCheckNameAvailabilityParameters)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:439:8 ($.definitions.StorageAccountCheckNameAvailabilityParameters.properties.name)
@@ -19,8 +34,8 @@
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:726:8 ($.definitions.StorageAccountRegenerateKeyParameters.properties.keyName)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:74:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].put)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:800:4 ($.definitions.Resource)
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 WARNING (DescriptionAndTitleMissing/R4000/SDKViolation): 'keyName' model/property lacks 'description' and 'title' property. Consider adding a 'description'/'title' element. Accurate description/title is essential for maintaining reference documentation.
 WARNING (DescriptionAndTitleMissing/R4000/SDKViolation): 'name' model/property lacks 'description' and 'title' property. Consider adding a 'description'/'title' element. Accurate description/title is essential for maintaining reference documentation.
@@ -39,7 +54,4 @@ WARNING (EnumInsteadOfBoolean/R3018/RPCViolation): Booleans are not descriptive
 WARNING (NonApplicationJsonType/R2004/RPCViolation): Only 'application/json' content-type is supported by ARM.
 WARNING (NonApplicationJsonType/R2004/RPCViolation): Only 'application/json' content-type is supported by ARM.
 WARNING (OperationIdNounConflictingModelNames/R2063/SDKViolation): OperationId has a noun that conflicts with one of the model names in definitions section. The model name will be disambiguated to 'UsageModel'. Consider using the plural form of 'Usage' to avoid this. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change.
-WARNING (PostOperationIdContainsUrlVerb/R2066/SDKViolation): OperationId should contain the verb: '/subscriptions/{subscriptionid}/providers/microsoft.storage/checknameavailability' in:'StorageAccounts_CheckNameAvailability'. Consider updating the operationId
-WARNING (PostOperationIdContainsUrlVerb/R2066/SDKViolation): OperationId should contain the verb: '/subscriptions/{subscriptionid}/resourcegroups/{resourcegroupname}/providers/microsoft.storage/storageaccounts/{accountname}/listkeys' in:'StorageAccounts_ListKeys'. Consider updating the operationId
-WARNING (PostOperationIdContainsUrlVerb/R2066/SDKViolation): OperationId should contain the verb: '/subscriptions/{subscriptionid}/resourcegroups/{resourcegroupname}/providers/microsoft.storage/storageaccounts/{accountname}/regeneratekey' in:'StorageAccounts_RegenerateKey'. Consider updating the operationId
 WARNING (PutRequestResponseScheme/R2017/SDKViolation): A PUT operation request body schema should be the same as its 200 response schema, to allow reusing the same entity between GET and PUT. If the schema of the PUT request body is a superset of the GET response body, make sure you have a PATCH operation to make the resource updatable. Operation: 'StorageAccounts_Create' Request Model: 'StorageAccountCreateParameters' Response Model: 'StorageAccount'

Samples/3a-literate-swagger/shell/stderr.txt

@@ -1,3 +1,10 @@
+
+
+
+
+
+
+
     - /Samples/3a-literate-swagger/swagger.md:137:0 ($.paths)
     - /Samples/3a-literate-swagger/swagger.md:139:4 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{serviceName}"].put)
     - /Samples/3a-literate-swagger/swagger.md:139:4 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{serviceName}"].put)

Samples/3a-literate-swagger/shell/stdout.txt

@@ -1,3 +1,17 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     - /Samples/3a-literate-swagger/swagger.md:139:4 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{serviceName}"].put)
     - /Samples/3a-literate-swagger/swagger.md:139:4 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{serviceName}"].put)
     - /Samples/3a-literate-swagger/swagger.md:178:4 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{serviceName}"].delete)
@@ -12,8 +26,8 @@
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-network/2016-09-01/swagger/network.json:43:8 ($.definitions.ErrorDetails.properties.code)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-network/2016-09-01/swagger/network.json:46:8 ($.definitions.ErrorDetails.properties.target)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-network/2016-09-01/swagger/network.json:49:8 ($.definitions.ErrorDetails.properties.message)
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 WARNING (AvoidNestedProperties/R2001/SDKViolation): Consider using x-ms-client-flatten to provide a better end user experience
 WARNING (DescriptionAndTitleMissing/R4000/SDKViolation): 'code' model/property lacks 'description' and 'title' property. Consider adding a 'description'/'title' element. Accurate description/title is essential for maintaining reference documentation.

Samples/3b-custom-transformations/generated/configuration.yaml

@@ -79,9 +79,12 @@ output-artifact:
   - code-model-v1.yaml
   - pipeline.yaml
   - configuration.yaml
+  - null
+  - help
   - source-file-csharp
   - source-file-jsonrpcclient
 output-folder: generated
+perform-load: true
 pipeline:
   configuration-emitter:
     scope: scope-configuration-emitter
@@ -131,6 +134,12 @@ pipeline:
     scope: scope-transform-string
     suffixes:
       - ''
+  help/help-autorest:
+    scope: help
+    suffixes: []
+  help/help-autorest-core:
+    scope: help
+    suffixes: []
   jsonrpcclient/emitter:
     input: transform
     scope: scope-jsonrpcclient/emitter
@@ -176,6 +185,7 @@ pipeline:
       - ''
   swagger-document-override/md-override-loader:
     output-artifact: immediate-config
+    scope: perform-load
     suffixes:
       - ''
   swagger-document/classic-openapi-validator:
@@ -220,6 +230,7 @@ pipeline:
       - ''
   swagger-document/loader:
     output-artifact: swagger-document
+    scope: perform-load
     suffixes:
       - ''
   swagger-document/model-validator:

Samples/3b-custom-transformations/generated/pipeline.yaml

@@ -6,6 +6,7 @@ configuration-emitter:
   pluginName: configuration-emitter
 csharp/cm/emitter:
   configScope:
+    - perform-load
     - csharp
     - scope-cm/emitter
   inputs:
@@ -13,6 +14,7 @@ csharp/cm/emitter:
   pluginName: emitter
 csharp/cm/transform:
   configScope:
+    - perform-load
     - csharp
   inputs:
     - csharp/commonmarker
@@ -20,6 +22,7 @@ csharp/cm/transform:
   pluginName: transform
 csharp/commonmarker:
   configScope:
+    - perform-load
     - csharp
   inputs:
     - csharp/imodeler1
@@ -27,6 +30,7 @@ csharp/commonmarker:
   pluginName: commonmarker
 csharp/emitter:
   configScope:
+    - perform-load
     - csharp
     - scope-transform-string
     - scope-csharp/emitter
@@ -35,6 +39,7 @@ csharp/emitter:
   pluginName: emitter
 csharp/generate:
   configScope:
+    - perform-load
     - csharp
   inputs:
     - csharp/cm/transform
@@ -42,6 +47,7 @@ csharp/generate:
   pluginName: csharp
 csharp/imodeler1:
   configScope:
+    - perform-load
     - csharp
   inputs:
     - openapi-document/identity
@@ -49,6 +55,7 @@ csharp/imodeler1:
   pluginName: imodeler1
 csharp/simplifier:
   configScope:
+    - perform-load
     - csharp
   inputs:
     - csharp/generate
@@ -56,6 +63,7 @@ csharp/simplifier:
   pluginName: csharp-simplifier
 csharp/transform:
   configScope:
+    - perform-load
     - csharp
     - scope-transform-string
   inputs:
@@ -64,24 +72,28 @@ csharp/transform:
   pluginName: transform
 openapi-document/emitter:
   configScope:
+    - perform-load
     - scope-openapi-document/emitter
   inputs:
     - openapi-document/identity
   pluginName: emitter
 openapi-document/identity:
-  configScope: []
+  configScope:
+    - perform-load
   inputs:
     - openapi-document/transform
   outputArtifact: openapi-document
   pluginName: identity
 openapi-document/openapi-document-converter:
-  configScope: []
+  configScope:
+    - perform-load
   inputs:
     - swagger-document/identity
   outputArtifact: openapi-document
   pluginName: openapi-document-converter
 openapi-document/transform:
-  configScope: []
+  configScope:
+    - perform-load
   inputs:
     - openapi-document/openapi-document-converter
   outputArtifact: openapi-document
@@ -92,77 +104,90 @@ pipeline-emitter:
   inputs: []
   pluginName: pipeline-emitter
 swagger-document-override/md-override-loader:
-  configScope: []
+  configScope:
+    - perform-load
   inputs: []
   outputArtifact: immediate-config
   pluginName: md-override-loader
 swagger-document/classic-openapi-validator:
   configScope:
+    - perform-load
     - azure-validator-composed
   inputs:
     - swagger-document/identity
   pluginName: classic-openapi-validator
 swagger-document/compose:
-  configScope: []
+  configScope:
+    - perform-load
   inputs:
     - swagger-document/individual/identity
   outputArtifact: swagger-document
   pluginName: compose
 swagger-document/emitter:
   configScope:
+    - perform-load
     - scope-swagger-document/emitter
   inputs:
     - swagger-document/identity
   pluginName: emitter
 swagger-document/identity:
-  configScope: []
+  configScope:
+    - perform-load
   inputs:
     - swagger-document/transform
   outputArtifact: swagger-document
   pluginName: identity
 swagger-document/individual/classic-openapi-validator:
   configScope:
+    - perform-load
     - azure-validator-individual
   inputs:
     - swagger-document/individual/identity
   pluginName: classic-openapi-validator
 swagger-document/individual/identity:
-  configScope: []
+  configScope:
+    - perform-load
   inputs:
     - swagger-document/individual/transform
   outputArtifact: swagger-document
   pluginName: identity
 swagger-document/individual/openapi-validator:
   configScope:
+    - perform-load
     - azure-validator-individual
   inputs:
     - swagger-document/individual/identity
   pluginName: openapi-validator
 swagger-document/individual/transform:
-  configScope: []
+  configScope:
+    - perform-load
   inputs:
     - swagger-document/loader
   outputArtifact: swagger-document
   pluginName: transform
 swagger-document/loader:
-  configScope: []
+  configScope:
+    - perform-load
   inputs: []
   outputArtifact: swagger-document
   pluginName: loader
 swagger-document/openapi-validator:
   configScope:
+    - perform-load
     - azure-validator-composed
   inputs:
     - swagger-document/identity
   pluginName: openapi-validator
 swagger-document/transform:
-  configScope: []
+  configScope:
+    - perform-load
   inputs:
     - swagger-document/transform-immediate
   outputArtifact: swagger-document
   pluginName: transform
 swagger-document/transform-immediate:
-  configScope: []
+  configScope:
+    - perform-load
   inputs:
     - swagger-document-override/md-override-loader
     - swagger-document/compose

Samples/3b-custom-transformations/shell/stderr.txt

@@ -1,3 +1,14 @@
+
+
+
+
+
+
+
+
+
+
+
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:126:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].delete)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:165:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].get)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:204:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].patch)

Samples/3b-custom-transformations/shell/stdout.txt

@@ -1,8 +1,23 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:14:4 ($.consumes[1])
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:18:4 ($.produces[1])
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:254:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/listKeys"].post)
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:358:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/regenerateKey"].post)
-    - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:40:6 ($.paths["/subscriptions/{subscriptionId}/providers/Microsoft.Storage/checkNameAvailability"].post)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:412:8 ($.paths["/subscriptions/{subscriptionId}/providers/Microsoft.Storage/usages"].get.operationId)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:437:4 ($.definitions.StorageAccountCheckNameAvailabilityParameters)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:439:8 ($.definitions.StorageAccountCheckNameAvailabilityParameters.properties.name)
@@ -19,8 +34,8 @@
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:726:8 ($.definitions.StorageAccountRegenerateKeyParameters.properties.keyName)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:74:6 ($.paths["/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}"].put)
     - https://raw.githubusercontent.com/Azure/azure-rest-api-specs/d374d03801e97737ddb32e01f20513e7b2bbd9c3/arm-storage/2015-06-15/swagger/storage.json:800:4 ($.definitions.Resource)
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 WARNING (DescriptionAndTitleMissing/R4000/SDKViolation): 'keyName' model/property lacks 'description' and 'title' property. Consider adding a 'description'/'title' element. Accurate description/title is essential for maintaining reference documentation.
 WARNING (DescriptionAndTitleMissing/R4000/SDKViolation): 'name' model/property lacks 'description' and 'title' property. Consider adding a 'description'/'title' element. Accurate description/title is essential for maintaining reference documentation.
@@ -39,7 +54,4 @@ WARNING (EnumInsteadOfBoolean/R3018/RPCViolation): Booleans are not descriptive
 WARNING (NonApplicationJsonType/R2004/RPCViolation): Only 'application/json' content-type is supported by ARM.
 WARNING (NonApplicationJsonType/R2004/RPCViolation): Only 'application/json' content-type is supported by ARM.
 WARNING (OperationIdNounConflictingModelNames/R2063/SDKViolation): OperationId has a noun that conflicts with one of the model names in definitions section. The model name will be disambiguated to 'UsageModel'. Consider using the plural form of 'Usage' to avoid this. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change.
-WARNING (PostOperationIdContainsUrlVerb/R2066/SDKViolation): OperationId should contain the verb: '/subscriptions/{subscriptionid}/providers/microsoft.storage/checknameavailability' in:'StorageAccounts_CheckNameAvailability'. Consider updating the operationId
-WARNING (PostOperationIdContainsUrlVerb/R2066/SDKViolation): OperationId should contain the verb: '/subscriptions/{subscriptionid}/resourcegroups/{resourcegroupname}/providers/microsoft.storage/storageaccounts/{accountname}/listkeys' in:'StorageAccounts_ListKeys'. Consider updating the operationId
-WARNING (PostOperationIdContainsUrlVerb/R2066/SDKViolation): OperationId should contain the verb: '/subscriptions/{subscriptionid}/resourcegroups/{resourcegroupname}/providers/microsoft.storage/storageaccounts/{accountname}/regeneratekey' in:'StorageAccounts_RegenerateKey'. Consider updating the operationId
 WARNING (PutRequestResponseScheme/R2017/SDKViolation): A PUT operation request body schema should be the same as its 200 response schema, to allow reusing the same entity between GET and PUT. If the schema of the PUT request body is a superset of the GET response body, make sure you have a PATCH operation to make the resource updatable. Operation: 'StorageAccounts_Create' Request Model: 'StorageAccountCreateParameters' Response Model: 'StorageAccount'

Samples/3c-guards/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/3d-custom-validation/shell/stdout.txt

@@ -1,8 +1,8 @@
     - trans_input?mem:1:0
     - trans_input?mem:1:0
     - trans_input?mem:1:0
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 WARNING: Custom test failed
 WARNING: Custom test failed

Samples/3e-batch-mode/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/3f-example-generation/shell/stdout.txt

@@ -1,5 +1,5 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 WARNING: 195 exported name(s) unnecessarily contains the service name. Please consider removing the service name.
 WARNING: Did not generate example 'Create load balancer' of 'loadBalancers/beginCreateOrUpdate'

Samples/3g-require-config/shell/stdout.txt

@@ -1,4 +1,4 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 Including configuration file '/Samples/1a-code-generation-minimal/readme.md'

Samples/test/additional-properties-boolean/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/empty-class/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/end-to-end/network/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/error-behavior/config-bad-syntax/shell/stdout.txt

@@ -1,4 +1,4 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
 [OperationAbortedException] Error occurred. Exiting.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/error-behavior/openapi-json-bad-syntax/shell/stderr.txt

@@ -1,6 +1,5 @@
     - /Samples/test/error-behavior/openapi-json-bad-syntax/tiny.json:45:6
-   at ...
+  Error: Syntax errors encountered.
 ERROR: Syntax error: missed comma between flow collection entries
-Error: Syntax errors encountered.
 FATAL: Error: Syntax errors encountered.
 FATAL: swagger-document/loader - FAILED

Samples/test/error-behavior/openapi-json-bad-syntax/shell/stdout.txt

@@ -1,4 +1,4 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 Process() Cancelled due to exception : Syntax errors encountered.

Samples/test/error-behavior/openapi-json-good/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/error-behavior/openapi-md-bad-fence/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/error-behavior/openapi-md-bad-syntax/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/error-behavior/openapi-md-good/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/error-behavior/openapi-not-swagger/shell/stderr.txt

@@ -1,4 +1,3 @@
-   at ...
+  Error: File '/Samples/test/error-behavior/openapi-not-swagger/tiny.json' is not a valid OpenAPI 2.0 definition (expected 'swagger: 2.0')
-Error: File '/Samples/test/error-behavior/openapi-not-swagger/tiny.json' is not a valid OpenAPI 2.0 definition (expected 'swagger: 2.0')
 FATAL: Error: File '/Samples/test/error-behavior/openapi-not-swagger/tiny.json' is not a valid OpenAPI 2.0 definition (expected 'swagger: 2.0')
 FATAL: swagger-document/loader - FAILED

Samples/test/error-behavior/openapi-not-swagger/shell/stdout.txt

@@ -1,4 +1,4 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 Process() Cancelled due to exception : File '/Samples/test/error-behavior/openapi-not-swagger/tiny.json' is not a valid OpenAPI 2.0 definition (expected 'swagger: 2.0')

Samples/test/error-behavior/openapi-yaml-bad-file-reference/shell/stderr.txt

@@ -1,4 +1,4 @@
-    - /Samples/test/error-behavior/openapi-yaml-bad-file-reference/tiny.yaml ($)
+    - /Samples/test/error-behavior/openapi-yaml-bad-file-reference/tiny.yaml:23:10 ($.paths["/cowbell"].post.parameters[0].schema["$ref"])
 ERROR: Referenced file '/Samples/test/error-behavior/openapi-yaml-bad-file-reference/i-do-not-exist.json' not found
 FATAL: Error: [OperationAbortedException] Error occurred. Exiting.
 FATAL: swagger-document/loader - FAILED

Samples/test/error-behavior/openapi-yaml-bad-file-reference/shell/stdout.txt

@@ -1,4 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
-WARNING: Failed to blame {"path":[]} in '"/Samples/test/error-behavior/openapi-yaml-bad-file-reference/tiny.yaml"' (Error: Object '/Samples/test/error-behavior/openapi-yaml-bad-file-reference/tiny.yaml' does not exist.)

Samples/test/error-behavior/openapi-yaml-bad-reference/shell/stderr.txt

@@ -1,15 +1,3 @@
-        components: [Object] } } }
+  Error: Could not resolve reference #/definitions/Cowball
-        info: [Object],
-        paths: [Object],
-        schemes: [Array],
-        servers: [Array],
-      { openapi: '3.0.0',
-     cache: {},
-     externals: [],
-     openapi: 
-   { patch: true,
-   at ...
-{ Error: Could not resolve reference #/definitions/Cowball
 FATAL: Error: Could not resolve reference #/definitions/Cowball
 FATAL: openapi-document/openapi-document-converter - FAILED
-options: 

Samples/test/error-behavior/openapi-yaml-bad-reference/shell/stdout.txt

@@ -1,4 +1,4 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 Process() Cancelled due to exception : Could not resolve reference #/definitions/Cowball

Samples/test/error-behavior/openapi-yaml-bad-syntax/shell/stderr.txt

@@ -2,11 +2,10 @@
     - /Samples/test/error-behavior/openapi-yaml-bad-syntax/tiny.yaml:31:15
     - /Samples/test/error-behavior/openapi-yaml-bad-syntax/tiny.yaml:37:27
     - /Samples/test/error-behavior/openapi-yaml-bad-syntax/tiny.yaml:37:4
-   at ...
+  Error: Syntax errors encountered.
 ERROR: Syntax error: bad indentation of a mapping entry
 ERROR: Syntax error: bad indentation of a mapping entry
 ERROR: Syntax error: can not read an implicit mapping pair; a colon is missed
 ERROR: Syntax error: incomplete explicit mapping pair; a key node is missed
-Error: Syntax errors encountered.
 FATAL: Error: Syntax errors encountered.
 FATAL: swagger-document/loader - FAILED

Samples/test/error-behavior/openapi-yaml-bad-syntax/shell/stdout.txt

@@ -1,4 +1,4 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 Process() Cancelled due to exception : Syntax errors encountered.

Samples/test/error-behavior/openapi-yaml-bad-type/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/error-behavior/openapi-yaml-good/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/hidden-methods/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/remove-methods/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/shared-response-header-types/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

Samples/test/stream-with-content-type/shell/stdout.txt

@@ -1,5 +1,5 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest
 WARNING: 10 exported name(s) unnecessarily contains the service name. Please consider removing the service name.
 WARNING: The name 'A' unnecessarily contains the service name; the service name will be trimmed.

Samples/test/use-default-in-constructor/shell/stdout.txt

@@ -1,3 +1,3 @@
-(C) 2017 **Microsoft Corporation.**  
+(C) 2017 Microsoft Corporation.
-# AutoRest code generation utility [version: 2.0.0]
+AutoRest code generation utility [version: 2.0.0]
 https://aka.ms/autorest

src/autorest-core/app.ts

@@ -7,10 +7,36 @@ require('./static-loader.js').load(`${__dirname}/static_modules.fs`)
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
+
+// https://github.com/uxitten/polyfill/blob/master/string.polyfill.js
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/padEnd
+if (!String.prototype.padEnd) {
+  String.prototype.padEnd = function padEnd(targetLength, padString) {
+    targetLength = targetLength >> 0; //floor if number or convert non-number to 0;
+    padString = String(padString || ' ');
+    if (this.length > targetLength) {
+      return String(this);
+    }
+    else {
+      targetLength = targetLength - this.length;
+      if (targetLength > padString.length) {
+        padString += padString.repeat(targetLength / padString.length); //append to original to ensure we are longer than needed
+      }
+      return String(this) + padString.slice(0, targetLength);
+    }
+  };
+}
+
 require('events').EventEmitter.defaultMaxListeners = 100;
 process.env['ELECTRON_RUN_AS_NODE'] = "1";
 delete process.env['ELECTRON_NO_ATTACH_CONSOLE'];
 
+process.on("exit", () => {
+  Shutdown()
+});
+
+const color: (text: string) => string = (<any>global).color ? (<any>global).color : p => p;
+
 // start of autorest-ng
 // the console app starts for real here.
 
@@ -19,7 +45,7 @@ import { AutoRestConfigurationImpl, MergeConfigurations } from './lib/configurat
 import { Parse, Stringify } from "./lib/ref/yaml";
 import { CreateObject, nodes } from "./lib/ref/jsonpath";
 import { OutstandingTaskAwaiter } from "./lib/outstanding-task-awaiter";
-import { AutoRest, ConfigurationView, IsOpenApiDocument } from './lib/autorest-core';
+import { AutoRest, ConfigurationView, IsOpenApiDocument, Shutdown } from './lib/autorest-core';
 import { ShallowCopy } from "./lib/source-map/merging";
 import { Message, Channel } from "./lib/message";
 import { resolve as currentDirectory } from "path";
@@ -29,6 +55,7 @@ import { isLegacy, CreateConfiguration } from "./legacyCli";
 import { DataStore } from "./lib/data-store/data-store";
 import { EnhancedFileSystem, RealFileSystem } from './lib/file-system';
 import { Exception, OperationCanceledException } from "./lib/exception";
+import { Help } from "./help";
 
 function awaitable(child: ChildProcess): Promise<number> {
   return new Promise<number>((resolve, reject) => {
@@ -45,15 +72,15 @@ async function legacyMain(autorestArgs: string[]): Promise<number> {
   try {
     config = await CreateConfiguration(currentDirUri, dataStore.GetReadThroughScope(new RealFileSystem()), autorestArgs);
   } catch (e) {
-    console.error("Error: You have provided legacy command line arguments (single-dash syntax) that seem broken.");
+    console.error(color("!Error: You have provided legacy command line arguments (single-dash syntax) that seem broken."));
     console.error("");
-    console.error(
+    console.error(color(
-      "While AutoRest keeps on supporting the old CLI by converting it over to the new one internally, " +
+      "> While AutoRest keeps on supporting the old CLI by converting it over to the new one internally, \n" +
-      "it does not have crazy logic determining *what* is wrong with arguments, should conversion fail. " +
+      "> it does not have crazy logic determining *what* is wrong with arguments, should conversion fail. \n" +
-      "Please try fixing your arguments or consider moving to the new CLI. " +
+      "> Please try fixing your arguments or consider moving to the new CLI. \n" +
-      "Visit https://github.com/Azure/autorest/blob/master/docs/user/cli.md for information about the new CLI.");
+      "> isit https://github.com/Azure/autorest/blob/master/docs/user/cli.md for information about the new CLI."));
     console.error("");
-    console.error("Internal error: " + e);
+    console.error(color("!Internal error: " + e));
     return 1;
   }
 
@@ -167,15 +194,15 @@ function subscribeMessages(api: AutoRest, errorCounter: () => void) {
       case Channel.Debug:
       case Channel.Verbose:
       case Channel.Information:
-        console.log(m.FormattedMessage || m.Text);
+        console.log(color(m.FormattedMessage || m.Text));
         break;
       case Channel.Warning:
-        console.warn(m.FormattedMessage || m.Text);
+        console.log(color(m.FormattedMessage || m.Text));
         break;
       case Channel.Error:
       case Channel.Fatal:
         errorCounter();
-        console.error(m.FormattedMessage || m.Text);
+        console.error(color(m.FormattedMessage || m.Text));
         break;
     }
   });
@@ -267,6 +294,7 @@ async function currentMain(autorestArgs: string[]): Promise<number> {
   if (config["batch"]) {
     await batch(api);
   }
+
   else {
     const result = await api.Process().finish;
     if (result !== true) {
@@ -274,12 +302,47 @@ async function currentMain(autorestArgs: string[]): Promise<number> {
     }
   }
 
-  // perform file system operations.
+  if (config.HelpRequested) {
-  for (const folder of clearFolders) {
+    // no fs operations on --help! Instead, format and print artifacts to console.
-    try { await ClearFolder(folder); } catch (e) { }
+    // - print boilerplate help
-  }
+    console.log("");
-  for (const artifact of artifacts) {
+    console.log("");
-    await WriteString(artifact.uri, artifact.content);
+    console.log(color("**Usage**: autorest `[configuration-file.md] [...options]`"));
+    console.log("");
+    console.log(color("  See: https://aka.ms/autorest/cli for additional documentation"));
+    // - sort artifacts by name (then content, just for stability)
+    const helpArtifacts = artifacts.sort((a, b) => a.uri === b.uri ? (a.content > b.content ? 1 : -1) : (a.uri > b.uri ? 1 : -1));
+    // - format and print
+    for (const helpArtifact of helpArtifacts) {
+      const help: Help = Parse(helpArtifact.content, (message, index) => console.error(color(`!Parsing error at **${helpArtifact.uri}**:__${index}: ${message}__`)));
+      if (!help) {
+        continue;
+      }
+      const activatedBySuffix = help.activationScope ? ` (activated by --${help.activationScope})` : "";
+      console.log("");
+      console.log(color(`### ${help.categoryFriendlyName}${activatedBySuffix}`));
+      if (help.description) {
+        console.log(color(help.description));
+      }
+      console.log("");
+      for (const settingHelp of help.settings) {
+        const keyPart = `--${settingHelp.key}`;
+        const typePart = settingHelp.type ? `=<${settingHelp.type}>` : ` `;//`[=<boolean>]`;
+        let settingPart = `${keyPart}\`${typePart}\``;
+        // if (!settingHelp.required) {
+        //   settingPart = `[${settingPart}]`;
+        // }
+        console.log(color(`  ${settingPart.padEnd(30)}  **${settingHelp.description}**`));
+      }
+    }
+  } else {
+    // perform file system operations.
+    for (const folder of clearFolders) {
+      try { await ClearFolder(folder); } catch (e) { }
+    }
+    for (const artifact of artifacts) {
+      await WriteString(artifact.uri, artifact.content);
+    }
   }
 
   // return the exit code to the caller.
@@ -292,7 +355,7 @@ function shallowMerge(existing: any, more: any) {
       const value = more[key];
       if (value !== undefined) {
         /* if (existing[key]) {
-          Console.Log(`> Warning: ${key} is overwritten.`);
+          Console.Log(color(`> Warning: ${key} is overwritten.`));
         } */
         existing[key] = value;
       }
@@ -336,7 +399,7 @@ async function resourceSchemaBatch(api: AutoRest): Promise<number> {
       const content = await ReadUri(path);
       if (!await IsOpenApiDocument(content)) {
         exitcode++;
-        console.error(`File ${path} is not a OpenAPI file.`);
+        console.error(color(`!File ${path} is not a OpenAPI file.`));
         continue;
       }
 
@@ -430,18 +493,12 @@ async function main() {
 
     autorestArgs = process.argv.slice(2);
 
-    // temporary: --help displays legacy AutoRest's -Help message
-    if (autorestArgs.indexOf("--help") !== -1) {
-      await legacyMain(["-Help"]);
-      return;
-    }
-
     if (isLegacy(autorestArgs)) {
       exitcode = await legacyMain(autorestArgs);
     } else {
       exitcode = await currentMain(autorestArgs);
     }
-
+    await Shutdown();
     process.exit(exitcode);
   } catch (e) {
     // be very careful about the following check:
@@ -452,12 +509,14 @@ async function main() {
       } else {
         console.log(e.message);
       }
+      await Shutdown();
       process.exit(e.exitCode);
     }
 
     if (e !== false) {
-      console.error(e);
+      console.error(color(`!${e}`));
     }
+    await Shutdown();
     process.exit(1);
   }
 }

src/autorest-core/help.ts

@@ -0,0 +1,14 @@
+
+export interface Help {
+  categoryFriendlyName: string;  // e.g. "Output Verbosity", "C# generator"
+  activationScope?: string;      // e.g. "csharp"
+  description?: string;          // inline markdown allowed
+  settings: SettingHelp[];
+}
+
+export interface SettingHelp {
+  required?: boolean;   // defaults to "false"
+  key: string;          // e.g. "namespace"
+  type?: string;        // not specified => flag; otherwise, please use TypeScript syntax
+  description: string;  // inline markdown allowed
+}

src/autorest-core/lib/autorest-core.ts

@@ -109,19 +109,20 @@ export class AutoRest extends EventEmitter {
           }
         };
 
-        if (earlyCancel) {
-          this.Finished.Dispatch(false);
-          return false;
-        }
-
         if (view.InputFileUris.length === 0) {
           if (view.GetEntry("allow-no-input")) {
+            this.Finished.Dispatch(true);
             return true;
           } else {
             return new Exception("No input files provided.\n\nUse --help to get help information.");
           }
         }
 
+        if (earlyCancel) {
+          this.Finished.Dispatch(false);
+          return false;
+        }
+
         await Promise.race([
           RunPipeline(view, <IFileSystem>this.fileSystem),
           new Promise((_, rej) => view.CancellationToken.onCancellationRequested(() => rej("Cancellation requested.")))]);

src/autorest-core/lib/configuration.ts

@@ -134,10 +134,6 @@ export class DirectiveView {
     return ValuesOf<string>(this.directive["suppress"]);
   }
 
-  public get set(): Iterable<string> {
-    return ValuesOf<string>(this.directive["set"]);
-  }
-
   public get transform(): Iterable<string> {
     return ValuesOf<string>(this.directive["transform"]);
   }
@@ -358,11 +354,15 @@ export class ConfigurationView {
   }
 
   public get DebugMode(): boolean {
-    return this.config["debug"] as boolean;
+    return !!this.config["debug"];
   }
 
   public get VerboseMode(): boolean {
-    return this.config["verbose"] as boolean;
+    return !!this.config["verbose"];
+  }
+
+  public get HelpRequested(): boolean {
+    return !!this.config["help"];
   }
 
   public * GetNestedConfiguration(pluginName: string): Iterable<ConfigurationView> {
@@ -602,6 +602,8 @@ export class Configuration {
   }
 
   public static async shutdown() {
+    AutoRestExtension.killAll();
+
     for (const each in loadedExtensions) {
       const ext = loadedExtensions[each];
       if (ext.autorestExtension.hasValue) {
@@ -707,7 +709,7 @@ export class Configuration {
               // local package
               messageEmitter.Message.Dispatch({
                 Channel: Channel.Information,
-                Text: `Loading local AutoRest extension '${additionalExtension.name}' (${localPath})`
+                Text: `> Loading local AutoRest extension '${additionalExtension.name}' (${localPath})`
               });
 
               const pack = await extMgr.findPackage(additionalExtension.name, localPath);
@@ -724,7 +726,7 @@ export class Configuration {
               if (installedExtension) {
                 messageEmitter.Message.Dispatch({
                   Channel: Channel.Information,
-                  Text: `Loading AutoRest extension '${additionalExtension.name}' (${additionalExtension.source})`
+                  Text: `> Loading AutoRest extension '${additionalExtension.name}' (${additionalExtension.source})`
                 });
                 // start extension
                 ext = loadedExtensions[additionalExtension.fullyQualified] = {
@@ -736,7 +738,7 @@ export class Configuration {
                 const pack = await extMgr.findPackage(additionalExtension.name, additionalExtension.source);
                 messageEmitter.Message.Dispatch({
                   Channel: Channel.Information,
-                  Text: `Installing AutoRest extension '${additionalExtension.name}' (${additionalExtension.source})`
+                  Text: `> Installing AutoRest extension '${additionalExtension.name}' (${additionalExtension.source})`
                 });
                 const extension = await extMgr.installPackage(pack, false, 5 * 60 * 1000, (progressInit: any) => progressInit.Message.Subscribe((s: any, m: any) => tmpView.Message({ Text: m, Channel: Channel.Verbose })));
                 // start extension

src/autorest-core/lib/pipeline/commonmark-documentation.ts

@@ -15,13 +15,24 @@ import {
   ParseNode,
   StringifyAst,
   YAMLMap,
-  YAMLMapping
+  YAMLMapping,
-} from "../ref/yaml";
+  YAMLNodeWithPath,
+} from '../ref/yaml';
 import { IdentitySourceMapping } from "../source-map/merging";
 import { From } from "../ref/linq";
 import { DataHandle, DataSink } from '../data-store/data-store';
 
-function IsDocumentationField(path: JsonPath) {
+function IsDocumentationField(node: YAMLNodeWithPath) {
+  if (!node || !node.node.value || !node.node.value.value || typeof node.node.value.value !== "string") {
+    return false;
+  }
+  const path = node.path;
+  if (path.length < 2) {
+    return false;
+  }
+  if (path[path.length - 2] === "x-ms-examples") {
+    return false;
+  }
   const last = path[path.length - 1];
   return last === "Description" || last === "Summary";
 }
@@ -52,7 +63,7 @@ export async function ProcessCodeModel(codeModel: DataHandle, sink: DataSink): P
 
   // transform
   for (const d of Descendants(ast, [], true)) {
-    if (d.node.kind === Kind.MAPPING && IsDocumentationField(d.path)) {
+    if (d.node.kind === Kind.MAPPING && IsDocumentationField(d)) {
       const node = d.node as YAMLMapping;
       const rawMarkdown = node.value.value;
 

src/autorest-core/lib/pipeline/help.ts

@@ -0,0 +1,171 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { ReadUri, ResolveUri } from '../ref/uri';
+import { QuickDataSource } from '../data-store/data-store';
+import { Parse } from '../ref/yaml';
+import { Help } from "../../help";
+import { PipelinePlugin } from "./pipeline";
+
+export function GetPlugin_HelpAutoRest(): PipelinePlugin {
+  return async config => {
+    config.GeneratedFile.Dispatch({
+      type: "help",
+      uri: "_help-autorest.0.json",
+      content: JSON.stringify(<Help>{
+        categoryFriendlyName: "Overall Verbosity",
+        settings: [
+          // {
+          //   key: "quiet",
+          //   description: "suppress most output information"
+          // },
+          {
+            key: "verbose",
+            description: "display verbose logging information"
+          },
+          {
+            key: "debug",
+            description: "display debug logging information"
+          }
+        ]
+      })
+    });
+    config.GeneratedFile.Dispatch({
+      type: "help",
+      uri: "_help-autorest.1.json",
+      content: JSON.stringify(<Help>{
+        categoryFriendlyName: "Manage Installation",
+        settings: [
+          {
+            key: "info", // list-installed
+            description: "display information about the installed version of autorest and its extensions"
+          },
+          {
+            key: "list-available",
+            description: "display available AutoRest versions"
+          },
+          {
+            key: "reset",
+            description: "removes all autorest extensions and downloads the latest version of the autorest-core extension"
+          },
+          {
+            key: "preview",
+            description: "enables using autorest extensions that are not yet released"
+          },
+          {
+            key: "latest",
+            description: "installs the latest autorest-core extension"
+          },
+          {
+            key: "force",
+            description: "force the re-installation of the autorest-core extension and frameworks"
+          },
+          {
+            key: "version",
+            description: "use the specified version of the autorest-core extension",
+            type: "string"
+          }
+        ]
+      })
+    });
+    return new QuickDataSource([]);
+  };
+}
+
+export function GetPlugin_HelpAutoRestCore(): PipelinePlugin {
+  return async config => {
+    config.GeneratedFile.Dispatch({
+      type: "help",
+      uri: "_help-autorestCore.0.json",
+      content: JSON.stringify(<Help>{
+        categoryFriendlyName: "Core Settings and Switches",
+        settings: [
+          {
+            key: "help",
+            description: "display help (combine with flags like --csharp to get further details about specific functionality)"
+          },
+          {
+            key: "input-file",
+            type: "string | string[]",
+            description: "OpenAPI file to use as input (use this setting repeatedly to pass multiple files at once)"
+          },
+          {
+            key: "output-folder",
+            type: "string",
+            description: "target folder for generated artifacts; default: \"<base folder>/generated\""
+          },
+          {
+            key: "base-folder",
+            description: "path to resolve relative paths (input/output files/folders) against; default: directory of configuration file, current directory otherwise"
+          },
+          {
+            key: "message-format",
+            type: "\"regular\" | \"json\"",
+            description: "format of messages (e.g. from OpenAPI validation); default: \"regular\""
+          },
+        ]
+      })
+    });
+    config.GeneratedFile.Dispatch({
+      type: "help",
+      uri: "_help-autorestCore.1.json",
+      content: JSON.stringify(<Help>{
+        categoryFriendlyName: "Core Functionality",
+        description: "> While AutoRest can be extended arbitrarily by 3rd parties (say, with a custom generator),\n> we officially support and maintain the following functionality.\n> More specific help is shown when combining the following switches with `--help` .",
+        settings: [
+          {
+            key: "csharp",
+            description: "generate C# client code"
+          },
+          {
+            key: "go",
+            description: "generate Go client code"
+          },
+          {
+            key: "java",
+            description: "generate Java client code"
+          },
+          {
+            key: "python",
+            description: "generate Python client code"
+          },
+          {
+            key: "nodejs",
+            description: "generate NodeJS client code"
+          },
+          {
+            key: "typescript",
+            description: "generate TypeScript client code"
+          },
+          {
+            key: "ruby",
+            description: "generate Ruby client code"
+          },
+          {
+            key: "php",
+            description: "generate PHP client code"
+          },
+          {
+            key: "azureresourceschema",
+            description: "generate Azure resource schemas"
+          },
+          {
+            key: "model-validator",
+            description: "validates an OpenAPI document against linked examples (see https://github.com/Azure/azure-rest-api-specs/search?q=x-ms-examples )"
+          },
+          // {
+          //   key: "semantic-validator",
+          //   description: "validates semantic validation"
+          // },
+          {
+            key: "azure-validator",
+            description: "validates an OpenAPI document against guidelines to improve quality (and optionally Azure guidelines)"
+          },
+        ]
+      })
+    });
+    return new QuickDataSource([]);
+  };
+}

src/autorest-core/lib/pipeline/pipeline.ts

@@ -20,6 +20,8 @@ import { IFileSystem } from "../file-system";
 import { EmitArtifacts } from "./artifact-emitter";
 import { ComposeSwaggers, LoadLiterateSwaggerOverrides, LoadLiterateSwaggers } from './swagger-loader';
 import { ConvertOAI2toOAI3 } from "../openapi/conversion";
+import { Help } from '../../help';
+import { GetPlugin_HelpAutoRest, GetPlugin_HelpAutoRestCore } from "./help";
 
 export type PipelinePlugin = (config: ConfigurationView, input: DataSource, sink: DataSink) => Promise<DataSource>;
 interface PipelineNode {
@@ -29,10 +31,10 @@ interface PipelineNode {
   inputs: string[];
 };
 
-function CreatePluginIdentity(): PipelinePlugin {
+function GetPlugin_Identity(): PipelinePlugin {
   return async (config, input) => input;
 }
-function CreatePluginLoader(): PipelinePlugin {
+function GetPlugin_Loader(): PipelinePlugin {
   return async (config, input, sink) => {
     let inputs = config.InputFileUris;
     const swaggers = await LoadLiterateSwaggers(
@@ -46,7 +48,7 @@ function CreatePluginLoader(): PipelinePlugin {
     return new QuickDataSource(result);
   };
 }
-function CreatePluginMdOverrideLoader(): PipelinePlugin {
+function GetPlugin_MdOverrideLoader(): PipelinePlugin {
   return async (config, input, sink) => {
     let inputs = config.InputFileUris;
     const swaggers = await LoadLiterateSwaggerOverrides(
@@ -61,7 +63,6 @@ function CreatePluginMdOverrideLoader(): PipelinePlugin {
   };
 }
 
-
 function CreatePerFilePlugin(processorBuilder: (config: ConfigurationView) => Promise<(input: DataHandle, sink: DataSink) => Promise<DataHandle>>): PipelinePlugin {
   return async (config, input, sink) => {
     const processor = await processorBuilder(config);
@@ -75,20 +76,20 @@ function CreatePerFilePlugin(processorBuilder: (config: ConfigurationView) => Pr
     return new QuickDataSource(result);
   };
 }
-function CreatePluginOAI2toOAIx(): PipelinePlugin {
+function GetPlugin_OAI2toOAIx(): PipelinePlugin {
   return CreatePerFilePlugin(async config => async (fileIn, sink) => {
     const fileOut = await ConvertOAI2toOAI3(fileIn, sink);
     return await sink.Forward(fileIn.Description, fileOut);
   });
 }
-function CreatePluginYaml2Jsonx(): PipelinePlugin {
+function GetPlugin_Yaml2Jsonx(): PipelinePlugin {
   return CreatePerFilePlugin(async config => async (fileIn, sink) => {
     let ast = fileIn.ReadYamlAst();
     ast = ConvertYaml2Jsonx(ast);
     return await sink.WriteData(fileIn.Description, StringifyAst(ast));
   });
 }
-function CreatePluginJsonx2Yaml(): PipelinePlugin {
+function GetPlugin_Jsonx2Yaml(): PipelinePlugin {
   return CreatePerFilePlugin(async config => async (fileIn, sink) => {
     let ast = fileIn.ReadYamlAst();
     ast = ConvertJsonx2Yaml(ast);
@@ -96,7 +97,7 @@ function CreatePluginJsonx2Yaml(): PipelinePlugin {
   });
 }
 
-function CreatePluginTransformer(): PipelinePlugin {
+function GetPlugin_Transformer(): PipelinePlugin {
   return CreatePerFilePlugin(async config => {
     const isObject = config.GetEntry("is-object" as any) === false ? false : true;
     const manipulator = new Manipulator(config);
@@ -106,7 +107,7 @@ function CreatePluginTransformer(): PipelinePlugin {
     };
   });
 }
-function CreatePluginTransformerImmediate(): PipelinePlugin {
+function GetPlugin_TransformerImmediate(): PipelinePlugin {
   return async (config, input, sink) => {
     const isObject = config.GetEntry("is-object" as any) === false ? false : true;
     const files = await input.Enum(); // first all the immediate-configs, then a single swagger-document
@@ -118,7 +119,7 @@ function CreatePluginTransformerImmediate(): PipelinePlugin {
     return new QuickDataSource([await sink.Forward("swagger-document", fileOut)]);
   };
 }
-function CreatePluginComposer(): PipelinePlugin {
+function GetPlugin_Composer(): PipelinePlugin {
   return async (config, input, sink) => {
     const swaggers = await Promise.all((await input.Enum()).map(x => input.ReadStrict(x)));
     const overrideInfo = config.GetEntry("override-info");
@@ -128,7 +129,7 @@ function CreatePluginComposer(): PipelinePlugin {
     return new QuickDataSource([await sink.Forward("composed", swagger)]);
   };
 }
-function CreatePluginExternal(host: AutoRestExtension, pluginName: string): PipelinePlugin {
+function GetPlugin_External(host: AutoRestExtension, pluginName: string): PipelinePlugin {
   return async (config, input, sink) => {
     const plugin = await host;
     const pluginNames = await plugin.GetPluginNames(config.CancellationToken);
@@ -151,7 +152,7 @@ function CreatePluginExternal(host: AutoRestExtension, pluginName: string): Pipe
     return new QuickDataSource(results);
   };
 }
-function CreateCommonmarkProcessor(): PipelinePlugin {
+function GetPlugin_CommonmarkProcessor(): PipelinePlugin {
   return async (config, input, sink) => {
     const files = await input.Enum();
     const results: DataHandle[] = [];
@@ -164,7 +165,7 @@ function CreateCommonmarkProcessor(): PipelinePlugin {
     return new QuickDataSource(results);
   };
 }
-function CreateArtifactEmitter(inputOverride?: () => Promise<DataSource>): PipelinePlugin {
+function GetPlugin_ArtifactEmitter(inputOverride?: () => Promise<DataSource>): PipelinePlugin {
   return async (config, input, sink) => {
     if (inputOverride) {
       input = await inputOverride();
@@ -177,10 +178,10 @@ function CreateArtifactEmitter(inputOverride?: () => Promise<DataSource>): Pipel
 
     await EmitArtifacts(
       config,
-      config.GetEntry("input-artifact" as any),
+      config.GetEntry("input-artifact" as any) || null,
       key => ResolveUri(
         config.OutputFolderUri,
-        safeEval<string>(config.GetEntry("output-uri-expr" as any), { $key: key, $config: config.Raw })),
+        safeEval<string>(config.GetEntry("output-uri-expr" as any) || "$key", { $key: key, $config: config.Raw })),
       input,
       config.GetEntry("is-object" as any));
     return new QuickDataSource([]);
@@ -291,22 +292,24 @@ function BuildPipeline(config: ConfigurationView): { pipeline: { [name: string]:
 export async function RunPipeline(configView: ConfigurationView, fileSystem: IFileSystem): Promise<void> {
   // built-in plugins
   const plugins: { [name: string]: PipelinePlugin } = {
-    "identity": CreatePluginIdentity(),
+    "help-autorest": GetPlugin_HelpAutoRest(),
-    "loader": CreatePluginLoader(),
+    "help-autorest-core": GetPlugin_HelpAutoRestCore(),
-    "md-override-loader": CreatePluginMdOverrideLoader(),
+    "identity": GetPlugin_Identity(),
-    "transform": CreatePluginTransformer(),
+    "loader": GetPlugin_Loader(),
-    "transform-immediate": CreatePluginTransformerImmediate(),
+    "md-override-loader": GetPlugin_MdOverrideLoader(),
-    "compose": CreatePluginComposer(),
+    "transform": GetPlugin_Transformer(),
+    "transform-immediate": GetPlugin_TransformerImmediate(),
+    "compose": GetPlugin_Composer(),
     // TODO: replace with OAV again
-    "semantic-validator": CreatePluginIdentity(),
+    "semantic-validator": GetPlugin_Identity(),
 
-    "openapi-document-converter": CreatePluginOAI2toOAIx(),
+    "openapi-document-converter": GetPlugin_OAI2toOAIx(),
-    "yaml2jsonx": CreatePluginYaml2Jsonx(),
+    "yaml2jsonx": GetPlugin_Yaml2Jsonx(),
-    "jsonx2yaml": CreatePluginJsonx2Yaml(),
+    "jsonx2yaml": GetPlugin_Jsonx2Yaml(),
-    "commonmarker": CreateCommonmarkProcessor(),
+    "commonmarker": GetPlugin_CommonmarkProcessor(),
-    "emitter": CreateArtifactEmitter(),
+    "emitter": GetPlugin_ArtifactEmitter(),
-    "pipeline-emitter": CreateArtifactEmitter(async () => new QuickDataSource([await configView.DataStore.getDataSink().WriteObject("pipeline", pipeline.pipeline)])),
+    "pipeline-emitter": GetPlugin_ArtifactEmitter(async () => new QuickDataSource([await configView.DataStore.getDataSink().WriteObject("pipeline", pipeline.pipeline)])),
-    "configuration-emitter": CreateArtifactEmitter(async () => new QuickDataSource([await configView.DataStore.getDataSink().WriteObject("configuration", configView.Raw)]))
+    "configuration-emitter": GetPlugin_ArtifactEmitter(async () => new QuickDataSource([await configView.DataStore.getDataSink().WriteObject("configuration", configView.Raw)]))
   };
 
   // dynamically loaded, auto-discovered plugins
@@ -315,7 +318,7 @@ export async function RunPipeline(configView: ConfigurationView, fileSystem: IFi
     const extension = await GetExtension(useExtensionQualifiedName);
     for (const plugin of await extension.GetPluginNames(configView.CancellationToken)) {
       if (!plugins[plugin]) {
-        plugins[plugin] = CreatePluginExternal(extension, plugin);
+        plugins[plugin] = GetPlugin_External(extension, plugin);
         __extensionExtension[plugin] = extension;
       }
     }

src/autorest-core/lib/pipeline/plugin-endpoint.ts

@@ -34,10 +34,17 @@ interface IAutoRestPluginInitiatorEndpoint {
 export class AutoRestExtension extends EventEmitter {
   private static lastSessionId: number = 0;
   private static CreateSessionId(): string { return `session_${++AutoRestExtension.lastSessionId}`; }
+  private static processes = new Array<ChildProcess>();
 
   public kill() {
     this.childProcess.kill();
   }
+  public static killAll() {
+    for (const each of AutoRestExtension.processes) {
+      each.kill("SIGKILL");
+    }
+    AutoRestExtension.processes.length = 0;
+  }
 
   public static async FromModule(modulePath: string): Promise<AutoRestExtension> {
     const childProc = fork(modulePath, [], <any>{ silent: true });
@@ -47,7 +54,7 @@ export class AutoRestExtension extends EventEmitter {
   public static async FromChildProcess(extensionName: string, childProc: ChildProcess): Promise<AutoRestExtension> {
     const plugin = new AutoRestExtension(extensionName, childProc.stdout, childProc.stdin, childProc);
     childProc.stderr.pipe(process.stderr);
-
+    AutoRestExtension.processes.push(childProc);
     // poke the extension to detect trivial issues like process startup failure or protocol violations, ...
     if (!Array.isArray(await plugin.GetPluginNames(CancellationToken.None))) {
       throw new Exception(`Plugin '${extensionName}' violated the protocol ('GetPluginNames' returned unexpected object).`);

src/autorest-core/lib/pipeline/swagger-loader.ts

@@ -68,10 +68,11 @@ async function EnsureCompleteDefinitionIsPresent(
   }
 
   const references: YAMLNodeWithPath[] = [];
-  var currentDoc = externalFiles[currentFileUri].ReadYamlAst();
+  const currentDoc = externalFiles[currentFileUri];
+  const currentDocAst = currentDoc.ReadYamlAst();
   if (entityType == null || modelName == null) {
     // external references
-    for (const node of Descendants(currentDoc)) {
+    for (const node of Descendants(currentDocAst)) {
       if (isReferenceNode(node)) {
         if (!(node.node.value as string).startsWith("#")) {
           references.push(node);
@@ -80,7 +81,7 @@ async function EnsureCompleteDefinitionIsPresent(
     }
   } else {
     // references within external file
-    const model = ResolveRelativeNode(currentDoc, currentDoc, [entityType, modelName]);
+    const model = ResolveRelativeNode(currentDocAst, currentDocAst, [entityType, modelName]);
     for (const node of Descendants(model, [entityType, modelName])) {
       if (isReferenceNode(node)) {
         references.push(node);
@@ -91,7 +92,7 @@ async function EnsureCompleteDefinitionIsPresent(
   const inputs: DataHandle[] = [sourceDoc];
   for (const { node, path } of references) {
 
-    const complaintLocation: SourceLocation = { document: currentFileUri, Position: <any>{ path: path } };
+    const complaintLocation: SourceLocation = { document: currentDoc.key, Position: <any>{ path: path } };
 
     const refPath = node.value as string;
     if (refPath.indexOf("#") === -1) {
@@ -161,7 +162,7 @@ async function EnsureCompleteDefinitionIsPresent(
   if (entityType != null && modelName != null) {
     var reference = "#/" + entityType + "/" + modelName;
     const dependentRefs: YAMLNodeWithPath[] = [];
-    for (const node of Descendants(currentDoc)) {
+    for (const node of Descendants(currentDocAst)) {
       const path = node.path;
       if (path.length > 3 && path[path.length - 3] === "allOf" && isReferenceNode(node) && (node.node.value as string).indexOf(reference) !== -1) {
         dependentRefs.push(node);

src/autorest-core/package.json

@@ -43,14 +43,14 @@
     "mocha": "^4.0.1",
     "shx": "0.2.2",
     "mocha-typescript": "^1.1.7",
-    "static-link": "^0.2.2",
+    "static-link": "^0.2.3",
     "vscode-jsonrpc": "^3.3.1"
   },
   "static-link": {
     "entrypoints": [],
     "dependencies": {
-      "@microsoft.azure/async-io": "~1.0.22",
+      "@microsoft.azure/async-io": "~2.0.7",
-      "@microsoft.azure/extension": "~1.2.12",
+      "@microsoft.azure/extension": "^2.0.4",
       "vscode-languageserver": "3.4.3",
       "commonmark": "^0.27.0",
       "file-url": "^2.0.2",
@@ -65,9 +65,8 @@
       "untildify": "^3.0.2",
       "urijs": "^1.18.10",
       "vscode-jsonrpc": "^3.3.1",
-      "yaml-ast-parser": "https://github.com/olydis/yaml-ast-parser/releases/download/0.0.34/yaml-ast-parser-0.0.34.tgz",
+      "yaml-ast-parser": "https://github.com/olydis/yaml-ast-parser/releases/download/0.0.34/yaml-ast-parser-0.0.34.tgz"
-      "yargs": "^8.0.2"
     },
-    "patch": "const fs = require(`fs`); let txt = fs.readFileSync('./node_modules/npm/lib/install/action/extract.js','utf8').replace(`const ENABLE_WORKERS = process.platform === 'darwin'`, `const ENABLE_WORKERS = false;`); fs.writeFileSync('./node_modules/npm/lib/install/action/extract.js', txt ); txt = fs.readFileSync(`./node_modules/npm/lib/npm.js`,`utf8`).replace(`var j = parseJSON(fs.readFileSync(`, `var j = require(path.join(__dirname, '../package.json'));` ).replace(`path.join(__dirname, '../package.json')) + '')`,``); fs.writeFileSync(`./node_modules/npm/lib/npm.js`, txt ); "
+    "patch": "const fs = require(`fs`); let txt = fs.readFileSync('./node_modules/npm/lib/install/action/extract.js','utf8').replace(`const ENABLE_WORKERS = process.platform === 'darwin'`, `const ENABLE_WORKERS = false;`); fs.writeFileSync('./node_modules/npm/lib/install/action/extract.js', txt ); txt = fs.readFileSync(`./node_modules/npm/lib/npm.js`,`utf8`).replace(`var j = parseJSON(fs.readFileSync(`, `var j = require(path.join(__dirname, '../package.json'));` ).replace(`path.join(__dirname, '../package.json')) + '')`,``); fs.writeFileSync(`./node_modules/npm/lib/npm.js`, txt );  txt = fs.readFileSync('./node_modules/npm/lib/pack.js','utf8').replace(`require.main.filename`, `require.resolve('../bin/npm-cli.js')`); fs.writeFileSync('./node_modules/npm/lib/pack.js', txt );"
   }
 }

src/autorest-core/resources/default-configuration.md

@@ -107,25 +107,49 @@ scope-configuration-emitter:
     "configuration"
 ```
 
-#### Loading
+#### Help
 
-Note: We don't load anything if `--help` appears to be specified.
+``` yaml $(help)
+input-file: dummy # trick "no input file" checks... may wanna refactor at some point
+```
+
+``` yaml
+pipeline:
+  help/help-autorest:
+    scope: help
+  help/help-autorest-core:
+    scope: help
+
+output-artifact:
+  - null # so emitted help doesn't necessarily have to say its output-artifact
+  - help
+```
+
+Note: We don't load anything if `--help` is specified.
+
+``` yaml !$(help)
+perform-load: true # kick off loading
+```
+
+#### Loading
 
 Markdown documentation overrides:
 
-``` yaml !$(help)
+``` yaml
 pipeline:
   swagger-document-override/md-override-loader:
     output-artifact: immediate-config
+    scope: perform-load
 ```
 
 OpenAPI definitions:
 
-``` yaml !$(help)
+``` yaml
 pipeline:
   swagger-document/loader:
     # plugin: loader # IMPLICIT: default to last item if split by '/'
     output-artifact: swagger-document
+    scope: perform-load
   swagger-document/individual/transform:
     input: loader
     output-artifact: swagger-document
@@ -179,7 +203,7 @@ scope-openapi-document/emitter:
     $config["output-file"] || 
     ($config.namespace ? $config.namespace.replace(/:/g,'_') : undefined) || 
     $config["input-file"][0].split('/').reverse()[0].split('\\').reverse()[0].replace(/\.json$/, "")
-scope-cm/emitter:
+scope-cm/emitter: # can remove once every generator depends on recent modeler
   input-artifact: code-model-v1
   is-object: true
   output-uri-expr: |

src/autorest/app.ts

@@ -11,94 +11,67 @@ if (process.argv.indexOf("--no-upgrade-check") != -1) {
 }
 
 import { isFile } from "@microsoft.azure/async-io";
-import { cli, enhanceConsole } from "@microsoft.azure/console";
+import { Exception, LazyPromise } from "@microsoft.azure/tasks";
-import { Exception, LazyPromise } from "@microsoft.azure/polyfill";
-import { Enumerable as IEnumerable, From } from "linq-es2015";
 import { networkEnabled, rootFolder, extensionManager, availableVersions, corePackage, installedCores, tryRequire, resolvePathForLocalVersion, ensureAutorestHome, selectVersion, pkgVersion } from "./autorest-as-a-service"
 import { gt } from "semver";
+import chalk from "chalk"
 
-// Caution: This may swallow backslashes.
+function color(text: string): string {
-// This cost me ~1h of debugging why "console.log(join(homedir(), ".autorest"));" prints "C:\Users\jobader.autorest"... 
+  return text.
-// Or rather left me looking in the wrong place for a file not found error on "C:\Users\jobader.autorest\x\y\z" where the problem was really in "z"
+    replace(/\*\*(.*?)\*\*/gm, chalk.bold(`$1`)).
-enhanceConsole();
+    replace(/^# (.*)/gm, chalk.greenBright('$1')).
+    replace(/^## (.*)/gm, chalk.green('$1')).
+    replace(/^### (.*)/gm, chalk.cyanBright('$1')).
+    replace(/`(.+)`/gm, chalk.gray('$1')).
+    replace(/(https?:\/\/\S*)/gm, chalk.blue.bold.underline('$1')).
+    replace(/__(.*)__/gm, chalk.italic('$1')).
+    replace(/^>(.*)/gm, chalk.cyan('  $1')).
+    replace(/^!(.*)/gm, chalk.red.bold('  $1')).
+    replace(/^(ERROR) (.*?):(.*)/gm, `\n${chalk.red.bold('$1')} ${chalk.green('$2')}:$3`).
+    replace(/^(WARNING) (.*?):(.*)/gm, `\n${chalk.yellow.bold('$1')} ${chalk.green('$2')}:$3`).
+    replace(/^(\s* - \w*:\/\/\S*):(\d*):(\d*) (.*)/gm, `${chalk.cyan('$1')}:${chalk.cyan.bold('$2')}:${chalk.cyan.bold('$3')} $4`).
+    replace(/"(.*?)"/gm, chalk.gray('"$1"')).
+    replace(/'(.*?)'/gm, chalk.gray("'$1'"))
+}
 
-// heavy customization, restart from scratch
+(<any>global).color = color;
-cli.reset();
 
 // Suppress the banner if in json mode.
 if (process.argv.indexOf("--json") == -1 && process.argv.indexOf("--message-format=json") == -1) {
-  console.log(`# AutoRest code generation utility [version: ${pkgVersion}]\n(C) 2017 **Microsoft Corporation.**  \nhttps://aka.ms/autorest`);
+  console.log(chalk.green.bold.underline(`AutoRest code generation utility [version: ${chalk.white.bold(pkgVersion)}]`));
+  console.log(color(`(C) 2017 **Microsoft Corporation.**`));
+  console.log(chalk.blue.bold.underline(`https://aka.ms/autorest`));
 }
-const args = cli
+
-  .app("autorest")
+function parseArgs(autorestArgs: string[]): any {
-  .title("AutoRest code generation utility for OpenAPI")
+  const result: any = {};
-  .copyright("(C) 2017 **Microsoft Corporation.**")
+  for (const arg of autorestArgs) {
-  .usage("**\nUsage**: autorest [configuration-file.md] [...options]\n\n  See: https://aka.ms/autorest/cli for additional documentation")
+    const match = /^--([^=]+)(=(.+))?$/g.exec(arg);
-  .wrap(0)
+    if (match) {
-  .help("help", "`Show help information`")
+      const key = match[1];
-  .option("quiet", {
+      const rawValue = match[3] || "true";
-    describe: "`suppress most output information`",
+      let value;
-    type: "boolean",
+      try {
-    group: "### Output Verbosity",
+        value = JSON.parse(rawValue);
-  }).option("verbose", {
+        // restrict allowed types (because with great type selection comes great responsibility)
-    describe: "`display verbose logging information`",
+        if (typeof value !== "string" && typeof value !== "boolean") {
-    type: "boolean",
+          value = rawValue;
-    group: "### Output Verbosity",
+        }
-  })
+      } catch (e) {
-  .option("debug", {
+        value = rawValue;
-    describe: "`display debug logging information`",
+      }
-    type: "boolean",
+      result[key] = value;
-    group: "### Output Verbosity",
+    }
-  })
+  }
-  .option("info", {
+  return result;
-    alias: ["list-installed"],
+}
-    describe: "display information about the installed version of autorest and it's extensions",
+
-    type: "boolean",
+const args = parseArgs(process.argv);
-    group: "### Informational",
+(<any>global).__args = args;
-  })
+
-  .option("json", {
+// aliases
-    describe: "ouptut messages as json",
+args["info"] = args["info"] || args["list-installed"];
-    type: "boolean",
+args["preview"] = args["preview"] || args["prerelease"];
-    group: "### Informational",
-  })
-  .option("list-available", {
-    describe: "display available extensions",
-    type: "boolean",
-    group: "### Informational",
-  })
-  .option("skip-upgrade-check", {
-    describe: "disable check for new version of bootstrapper",
-    type: "boolean",
-    default: false,
-    group: "### Installation",
-  })
-  .option("reset", {
-    describe: "removes all autorest extensions and downloads the latest version of the autorest-core extension",
-    type: "boolean",
-    group: "### Installation",
-  })
-  .option("preview", {
-    alias: "prerelease",
-    describe: "enables using autorest extensions that are not yet released",
-    type: "boolean",
-    group: "### Installation",
-  })
-  .option("latest", {
-    describe: "installs the latest **autorest-core** extension",
-    type: "boolean",
-    group: "### Installation",
-  })
-  .option("force", {
-    describe: "force the re-installation of the **autorest-core** extension and frameworks",
-    type: "boolean",
-    group: "### Installation",
-  })
-  .option("version", {
-    describe: "use the specified version of the **autorest-core** extension",
-    type: "string",
-    group: "### Installation",
-  })
-  .argv;
 
 // argument tweakin'
 const preview: boolean = args.preview;
@@ -113,7 +86,7 @@ const checkBootstrapper = new LazyPromise(async () => {
     try {
       const pkg = await (await extensionManager).findPackage("autorest", preview ? "preview" : "latest");
       if (gt(pkg.version, pkgVersion)) {
-        console.log(`\n ## There is a new version of AutoRest available (${pkg.version}).\n > You can install the newer version with with \`npm install -g autorest@${preview ? "preview" : "latest"}\`\n`);
+        console.log(color(`\n## There is a new version of AutoRest available (${pkg.version}).\n > You can install the newer version with with \`npm install -g autorest@${preview ? "preview" : "latest"}\`\n`));
       }
     } catch (e) {
       // no message then.
@@ -128,7 +101,7 @@ async function showAvailableCores(): Promise<number> {
   const cores = await availableVersions();
   for (const v of cores) {
     max--;
-    table += `\n|${corePackage}|${v}|`;
+    table += `\n ${chalk.cyan.bold(corePackage.padEnd(30, ' '))} ${chalk.grey.bold(v.padEnd(14, ' '))} `;
     if (!max) {
       break;
     }
@@ -137,7 +110,7 @@ async function showAvailableCores(): Promise<number> {
     console.log(JSON.stringify(cores, null, "  "));
   } else {
     if (table) {
-      console.log("|Extension Name|Version|\n|-----|-----|" + table);
+      console.log(`${chalk.green.bold.underline(' Extension Name'.padEnd(30, ' '))}  ${chalk.green.bold.underline('Version'.padEnd(14, ' '))}\n${table}`);
     }
   }
   return 0;
@@ -149,16 +122,17 @@ async function showInstalledExtensions(): Promise<number> {
   let table = "";
   if (extensions.length > 0) {
     for (const extension of extensions) {
-      table += `\n|${extension.name === corePackage ? "core" : "extension"}|${extension.name}|${extension.version}|${extension.location}|`;
+
+      table += `\n ${chalk.cyan((extension.name === corePackage ? "core" : "extension").padEnd(10))} ${chalk.cyan.bold(extension.name.padEnd(40))} ${chalk.cyan(extension.version.padEnd(12))} ${chalk.cyan(extension.location)}`;
     }
   }
   if (args.json) {
     console.log(JSON.stringify(extensions, null, "  "));
   } else {
     if (table) {
-      console.log("# Showing All Installed Extensions\n\n|Type|Extension Name|Version|location|\n|-----|-----|----|" + table + "\n\n");
+      console.log(color(`\n\n# Showing All Installed Extensions\n\n ${chalk.underline('Type'.padEnd(10))} ${chalk.underline('Extension Name'.padEnd(40))} ${chalk.underline('Version'.padEnd(12))} ${chalk.underline('Location')} ${table}\n\n`));
     } else {
-      console.log("# Showing All Installed Extensions\n\n > No Extensions are currently installed.\n\n");
+      console.log(color("\n\n# Showing All Installed Extensions\n\n > No Extensions are currently installed.\n\n"));
     }
   }
   return 0;
@@ -181,11 +155,6 @@ async function main() {
     process.exit(await showInstalledExtensions());
   }
 
-  if (args.help) {
-    // yargs will print the help. We can leave now.
-    process.exit(0);
-  }
-
   // check to see if local installed core is available.
   const localVersion = resolvePathForLocalVersion(args.version && args.version !== '' ? requestedVersion : null);
 
@@ -197,20 +166,31 @@ async function main() {
   // if the resolved local version is actually a file, we'll try that as a package when we get there.
   if (await isFile(localVersion)) {
     // this should try to install the file.
-    console.trace(`Found local core package file: '${localVersion}'`);
+    if (args.debug) {
+      console.log(`Found local core package file: '${localVersion}'`);
+    }
     requestedVersion = localVersion;
   }
 
   // failing that, we'll continue on and see if NPM can do something with the version.
-  console.trace(`Network Enabled: ${await networkEnabled}`);
+  if (args.debug) {
+    console.log(`Network Enabled: ${await networkEnabled}`);
+  }
 
   try {
     /* make sure we have a .autorest folder */
     await ensureAutorestHome();
 
     if (args.reset) {
-      console.trace(`Resetting autorest extension folder '${rootFolder}'`);
+      if (args.debug) {
-      await (await extensionManager).reset();
+        console.log(`Resetting autorest extension folder '${rootFolder}'`);
+      }
+      try {
+        await (await extensionManager).reset();
+      } catch (e) {
+        console.log(color("\n\n## The AutoRest extension folder appears to be locked.\nDo you have a process that is currently using AutoRest (perhaps the vscode extension?).\n\nUnable to reset the extension folder, exiting."));
+        process.exit(10);
+      }
     }
 
     // wait for the bootstrapper check to finish.
@@ -222,9 +202,21 @@ async function main() {
     let selectedVersion = await selectVersion(requestedVersion, force);
 
     // let's strip the extra stuff from the command line before we require the core module.
-    const RemoveArgs = From<string>(["--version", "--list-installed", "--list-available", "--reset", "--latest", "--latest-release", "--runtime-id"]);
+    const oldArgs = process.argv;
-    // Remove bootstrapper args from cmdline
+    const newArgs = new Array<string>();
-    process.argv = From<string>(process.argv).Where(each => !RemoveArgs.Any(i => each === i || each.startsWith(`${i}=`) || each.startsWith(`${i}:`))).ToArray();
+
+    for (const each of process.argv) {
+      let keep = true;
+      for (const discard of ["--version", "--list-installed", "--list-available", "--reset", "--latest", "--latest-release", "--runtime-id"]) {
+        if (each === discard || each.startsWith(`${discard}=`) || each.startsWith(`${discard}:`)) {
+          keep = false;
+        }
+      }
+      if (keep) {
+        newArgs.push(each);
+      }
+    }
+    process.argv = newArgs;
 
     // use this to make the core aware that this run may be legal even without any inputs
     // this is a valid scenario for "preparation calls" to autorest like `autorest --reset` or `autorest --latest`
@@ -233,14 +225,16 @@ async function main() {
       process.argv.push("--allow-no-input");
     }
 
-    console.trace(`Starting ${corePackage} from ${await selectedVersion.location}`);
+    if (args.debug) {
+      console.log(`Starting ${corePackage} from ${await selectedVersion.location}`);
+    }
     if (!tryRequire(await selectedVersion.modulePath, "app.js")) {
       throw new Error(`Unable to start AutoRest Core from ${await selectedVersion.modulePath}`);
     }
   } catch (exception) {
-    console.log("Failure:");
+    console.log(chalk.redBright("Failure:"));
-    console.error(exception);
+    console.error(chalk.bold(exception));
-    console.error((<Error>exception).stack);
+    console.error(chalk.bold((<Error>exception).stack));
     process.exit(1);
   }
 }

src/autorest/autorest-as-a-service.ts

@@ -3,8 +3,8 @@ import { lookup } from "dns";
 import { Extension, ExtensionManager } from "@microsoft.azure/extension";
 import { homedir } from "os";
 import { dirname, join, resolve } from "path";
-import { Enumerable as IEnumerable, From } from "linq-es2015";
+
-import { Exception, LazyPromise } from "@microsoft.azure/polyfill";
+import { Exception, LazyPromise } from "@microsoft.azure/tasks";
 
 import * as semver from "semver";
 import { isFile, mkdir, isDirectory } from "@microsoft.azure/async-io";
@@ -12,6 +12,7 @@ import { isFile, mkdir, isDirectory } from "@microsoft.azure/async-io";
 export const pkgVersion: string = require(`${__dirname}/../package.json`).version;
 const home: string = process.env["autorest.home"] || homedir();
 process.env["autorest.home"] = home;
+const args = (<any>global).__args || {};
 
 export const rootFolder: string = join(home, ".autorest");
 
@@ -120,7 +121,7 @@ export async function ensureAutorestHome() {
 
 export async function selectVersion(requestedVersion: string, force: boolean, minimumVersion?: string) {
   const installedVersions = await installedCores();
-  let currentVersion = From(installedVersions).FirstOrDefault() || null;
+  let currentVersion = installedVersions[0] || null;
 
   // the consumer can say I want the latest-installed, but at least XXX.XXX
   if (minimumVersion && currentVersion && !semver.satisfies(currentVersion.version, minimumVersion)) {
@@ -128,22 +129,36 @@ export async function selectVersion(requestedVersion: string, force: boolean, mi
   }
 
   if (currentVersion) {
-    console.trace(`The most recent installed version is ${currentVersion.version}`);
+
+    if (args.debug) {
+      console.log(`The most recent installed version is ${currentVersion.version}`);
+    }
 
     if (requestedVersion === "latest-installed" || (requestedVersion === 'latest' && false == await networkEnabled)) {
-      console.trace(`requesting current version '${currentVersion.version}'`);
+      if (args.debug) {
+        console.log(`requesting current version '${currentVersion.version}'`);
+      }
       requestedVersion = currentVersion.version;
     }
   } else {
-    console.trace(`No ${corePackage} is installed.`);
+    if (args.debug) {
+      console.log(`No ${corePackage} is installed.`);
+    }
   }
 
-  let selectedVersion = From(installedVersions).FirstOrDefault(each => semver.satisfies(each.version, requestedVersion));
+  let selectedVersion: any = null;
+  for (const each of installedVersions) {
+    if (semver.satisfies(each.version, requestedVersion)) {
+      selectedVersion = each;
+    }
+  }
 
   // is the requested version installed?
   if (!selectedVersion || force) {
     if (!force) {
-      console.trace(`${requestedVersion} was not satisfied directly by a previous installation.`);
+      if (args.debug) {
+        console.log(`${requestedVersion} was not satisfied directly by a previous installation.`);
+      }
     }
 
     // if it's not a file, and the network isn't available, we can't continue.
@@ -164,7 +179,9 @@ export async function selectVersion(requestedVersion: string, force: boolean, mi
 
     const pkg = await (await extensionManager).findPackage(corePackage, requestedVersion);
     if (pkg) {
-      console.trace(`Selected package: ${pkg.name}@${pkg.version} => ${pkg.resolvedInfo.rawSpec} `);
+      if (args.debug) {
+        console.log(`Selected package: ${pkg.name}@${pkg.version} => ${pkg.resolvedInfo.rawSpec} `);
+      }
     } else {
       throw new Exception(`Unable to find a valid AutoRest Core package for '${requestedVersion}'.`);
     }
@@ -175,12 +192,18 @@ export async function selectVersion(requestedVersion: string, force: boolean, mi
 
     if (!selectedVersion || force) {
       // this will throw if there is an issue with installing the extension.
-      console.trace(`**Installing package** ${corePackage}@${pkg.version}\n[This will take a few moments...]`);
+      if (args.debug) {
+        console.log(`**Installing package** ${corePackage}@${pkg.version}\n[This will take a few moments...]`);
+      }
 
-      selectedVersion = await (await extensionManager).installPackage(pkg, force, 5 * 60 * 1000, installer => installer.Message.Subscribe((s, m) => { console.trace(`Installer: ${m}`); }));
+      selectedVersion = await (await extensionManager).installPackage(pkg, force, 5 * 60 * 1000, installer => installer.Message.Subscribe((s, m) => { if (args.debug) console.log(`Installer: ${m}`); }));
-      console.trace(`Extension location: ${selectedVersion.packageJsonPath}`);
+      if (args.debug) {
+        console.log(`Extension location: ${selectedVersion.packageJsonPath}`);
+      }
     } else {
-      console.trace(`AutoRest Core ${pkg.version} is available at ${selectedVersion.modulePath}`);
+      if (args.debug) {
+        console.log(`AutoRest Core ${pkg.version} is available at ${selectedVersion.modulePath}`);
+      }
     }
   }
   return selectedVersion;

src/autorest/interfaces/autorest-core.d.ts

@@ -269,6 +269,21 @@ export class EnhancedFileSystem implements IFileSystem {
     WriteFile(uri: string, content: string): Promise<void>;
 }
 
+}
+declare module 'autorest-core/help' {
+	export interface Help {
+    categoryFriendlyName: string;
+    activationScope?: string;
+    description?: string;
+    settings: SettingHelp[];
+}
+export interface SettingHelp {
+    required?: boolean;
+    key: string;
+    type?: string;
+    description: string;
+}
+
 }
 declare module 'autorest-core/lib/document-type' {
 	export enum DocumentType {
@@ -448,7 +463,6 @@ export class DirectiveView {
     readonly where: Iterable<string>;
     readonly reason: string | null;
     readonly suppress: Iterable<string>;
-    readonly set: Iterable<string>;
     readonly transform: Iterable<string>;
     readonly test: Iterable<string>;
 }
@@ -494,6 +508,7 @@ export class ConfigurationView {
     readonly Raw: AutoRestConfigurationImpl;
     readonly DebugMode: boolean;
     readonly VerboseMode: boolean;
+    readonly HelpRequested: boolean;
     GetNestedConfiguration(pluginName: string): Iterable<ConfigurationView>;
     GetNestedConfigurationImmediate(...scope: any[]): ConfigurationView;
     Message(m: Message): void;

src/autorest/package.json

@@ -30,7 +30,7 @@
     "test": "./node_modules/.bin/mocha ./dist/test",
     "build": "cd .. && cd autorest-core && npm run build && cd .. && cd autorest && tsc -p .&& shx mkdir -p ./dist/interfaces && shx cp -r ./interfaces/*.d.ts ./dist/interfaces ",
     "static-link": "static-link",
-    "postinstall": "node ./post-install --force",
+    "prepare": "node ./post-install --force",
     "preinstall": "node ./preinstall-check",
     "reinstall": "shx rm ./package-lock.json && shx rm -rf ./node_modules && npm install",
     "prepack": "static-link & npm run build"
@@ -40,23 +40,21 @@
     "@types/commonmark": "^0.22.29",
     "@types/node": "^7.0.5",
     "@types/semver": "^5.3.30",
-    "@types/yargs": "^6.6.0",
     "mocha": "3.2.0",
     "mocha-typescript": "1.0.22",
     "typescript": "2.5.3",
-    "static-link": "^0.2.2",
+    "static-link": "^0.2.3",
     "shx": "0.2.2"
   },
   "static-link": {
     "entrypoints": [],
     "dependencies": {
-      "@microsoft.azure/async-io": "~1.0.22",
+      "@microsoft.azure/async-io": "~2.0.7",
-      "@microsoft.azure/console": "~1.0.31",
+      "@microsoft.azure/extension": "^2.0.4",
-      "@microsoft.azure/extension": "~1.2.12",
+      "@microsoft.azure/tasks": "~2.0.12",
-      "@microsoft.azure/polyfill": "~1.0.17",
+      "semver": "^5.3.0",
-      "linq-es2015": "^2.4.24",
+      "chalk": "2.3.0"
-      "semver": "^5.3.0"
     },
-    "patch": "const fs = require(`fs`); let txt = fs.readFileSync('./node_modules/npm/lib/install/action/extract.js','utf8').replace(`const ENABLE_WORKERS = process.platform === 'darwin'`, `const ENABLE_WORKERS = false;`); fs.writeFileSync('./node_modules/npm/lib/install/action/extract.js', txt ); txt = fs.readFileSync(`./node_modules/npm/lib/npm.js`,`utf8`).replace(`var j = parseJSON(fs.readFileSync(`, `var j = require(path.join(__dirname, '../package.json'));` ).replace(`path.join(__dirname, '../package.json')) + '')`,``); fs.writeFileSync(`./node_modules/npm/lib/npm.js`, txt ); "
+    "patch": "const fs = require(`fs`); let txt = fs.readFileSync('./node_modules/npm/lib/install/action/extract.js','utf8').replace(`const ENABLE_WORKERS = process.platform === 'darwin'`, `const ENABLE_WORKERS = false;`); fs.writeFileSync('./node_modules/npm/lib/install/action/extract.js', txt ); txt = fs.readFileSync(`./node_modules/npm/lib/npm.js`,`utf8`).replace(`var j = parseJSON(fs.readFileSync(`, `var j = require(path.join(__dirname, '../package.json'));` ).replace(`path.join(__dirname, '../package.json')) + '')`,``); fs.writeFileSync(`./node_modules/npm/lib/npm.js`, txt );   txt = fs.readFileSync('./node_modules/npm/lib/pack.js','utf8').replace(`require.main.filename`, `require.resolve('../bin/npm-cli.js')`); fs.writeFileSync('./node_modules/npm/lib/pack.js', txt ); "
   }
 }