From 6ff09e7956b9ff736fe4e7dc32a20200d24b0ef7 Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Mon, 25 Jul 2022 18:49:16 -0700 Subject: [PATCH 01/13] Add errors handling cases for json output --- ...netListPackageMachineReadableJsonOutput.md | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index 7e2b62d5b2..80f74d4645 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -772,6 +772,139 @@ Outputs json for format version 1, if it's not specified then latest version'll } ``` +### Error handling + +In case of an error it would be written into `problems` section. But in case there is parameter, options error then it may defaults back to console output instead of json output. +Also in case of runtime there's error then it may not show json output at all because it needs all the data for json output before display. + +#### `> dotnet list package` + +`MyProjectB.csproj` was not restored. + +```dotnetcli +Project 'MyProjectA' has the following package references + [netcoreapp3.1]: + Top-level Package Requested Resolved + > Microsoft.Extensions.Primitives [1.0.0, 5.0.0] 1.0.0 + > NuGet.Commands 4.8.0-preview3.5278 4.8.0-preview3.5278 + > Text2Xml.Lib [1.1.2, 2.0.0) 1.1.2 + +No assets file was found for `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.csproj`. Please run restore before running this command. +``` + +#### `> dotnet list package --format json` + +```json +{ + "version": 1, + "parameters": "", + "problems": [ + "No assets file was found for `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`. Please run restore before running this command." + ], + "projects": [ + { + "path": "src/lib/MyProjectA.csproj", + "frameworks": [ + { + "framework": "netcoreapp3.1", + "topLevelPackages": [ + { + "id": "Microsoft.Extensions.Primitives", + "requestedVersion": "[1.0.0, 5.0.0]", + "resolvedVersion": "1.0.0" + }, + { + "id": "NuGet.Commands", + "requestedVersion": "4.8.0-preview3.5278", + "resolvedVersion": "4.8.0-preview3.5278" + }, + { + "id": "Text2Xml.Lib", + "requestedVersion": "[1.1.2, 2.0.0)", + "resolvedVersion": "1.1.2" + } + ] + } + ] + } + ] +} +``` + +#### `> dotnet list NonExisting.csproj package` + +`NonExisting.csproj` doesn't exist or wrong path. + +```dotnetcli +Could not find file or directory 'C:\Users\userA\repos\MainApp\src\lib\NonExisting.csproj'. +``` + +#### `> dotnet list package --format json` + +```json +{ + "version": 1, + "parameters": "", + "problems": [ + "Could not find file or directory 'C:/Users/userA/repos/MainApp/src/lib/NonExisting.csproj'" + ] +} +``` + +#### `> dotnet list package` + +`MyProjectB` is package.config type project, so it's not supported. + +```dotnetcli +Project 'MyProjectA' has the following package references + [netcoreapp3.1]: + Top-level Package Requested Resolved + > Microsoft.Extensions.Primitives [1.0.0, 5.0.0] 1.0.0 + > NuGet.Commands 4.8.0-preview3.5278 4.8.0-preview3.5278 + > Text2Xml.Lib [1.1.2, 2.0.0) 1.1.2 + +The project `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.csproj` uses package.config for NuGet packages, while the command works only with package reference projects. +``` + +#### `> dotnet list package --format json` + +```json +{ + "version": 1, + "parameters": "", + "problems": [ + "The project `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`` uses package.config for NuGet packages, while the command works only with package reference projects." + ], + "projects": [ + { + "path": "src/lib/MyProjectA.csproj", + "frameworks": [ + { + "framework": "netcoreapp3.1", + "topLevelPackages": [ + { + "id": "Microsoft.Extensions.Primitives", + "requestedVersion": "[1.0.0, 5.0.0]", + "resolvedVersion": "1.0.0" + }, + { + "id": "NuGet.Commands", + "requestedVersion": "4.8.0-preview3.5278", + "resolvedVersion": "4.8.0-preview3.5278" + }, + { + "id": "Text2Xml.Lib", + "requestedVersion": "[1.1.2, 2.0.0)", + "resolvedVersion": "1.1.2" + } + ] + } + ] + } + ] +} +``` + ## Compatibility We start with `version 1`, as long as we don't remove or rename then it'll be backward compatible. In case [we change version](https://stackoverflow.com/a/13945074) just add new properties, keep old ones even it's not used. From 918a269099422f4508fe6fb0f1fbe29dfdff3ad4 Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Wed, 27 Jul 2022 09:02:02 -0700 Subject: [PATCH 02/13] Return non-zero result --- ...netListPackageMachineReadableJsonOutput.md | 45 ++++++++++++++++--- 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index 80f74d4645..bfebbb4a20 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -774,7 +774,9 @@ Outputs json for format version 1, if it's not specified then latest version'll ### Error handling -In case of an error it would be written into `problems` section. But in case there is parameter, options error then it may defaults back to console output instead of json output. +In case of an error it would be written into `problems` section and return non-zero error exit code to indicate there had been some error to help scripting use cases. +For current implementation we'll returns general error code `1` from application, more specific error code for each error scenario is not considered in this spec scope. +In case there is parameter, options error then it may defaults back to console output instead of json output. Also in case of runtime there's error then it may not show json output at all because it needs all the data for json output before display. #### `> dotnet list package` @@ -799,7 +801,10 @@ No assets file was found for `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.cs "version": 1, "parameters": "", "problems": [ - "No assets file was found for `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`. Please run restore before running this command." + { + "project": "src/lib/MyProjectA.csproj", + "message": "No assets file was found for `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`. Please run restore before running this command." + } ], "projects": [ { @@ -846,7 +851,10 @@ Could not find file or directory 'C:\Users\userA\repos\MainApp\src\lib\NonExisti "version": 1, "parameters": "", "problems": [ - "Could not find file or directory 'C:/Users/userA/repos/MainApp/src/lib/NonExisting.csproj'" + { + "project": "src/lib/NonExisting.csproj", + "message": "Could not find file or directory 'C:/Users/userA/repos/MainApp/src/lib/NonExisting.csproj'" + } ] } ``` @@ -873,7 +881,10 @@ The project `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.csproj` uses packag "version": 1, "parameters": "", "problems": [ - "The project `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`` uses package.config for NuGet packages, while the command works only with package reference projects." + { + "project": "src/lib/MyProjectB.csproj", + "message": "The project `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`` uses package.config for NuGet packages, while the command works only with package reference projects." + } ], "projects": [ { @@ -905,6 +916,28 @@ The project `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.csproj` uses packag } ``` +#### `> dotnet list package --format json --output-version 3` + +Since output version `3` is not available, then it'll default to latest available version, and log about unsupported format version request into json result. + +```json +{ + "version": 1, + "parameters": "", + "problems": [ + { + "message": "Unsupported output format version 3 was requested. Defaulting to latest available format version 1." + } + ], + "projects": [ + { + "path": "src/lib/MyProjectA.csproj", + ... + } + ] +} +``` + ## Compatibility We start with `version 1`, as long as we don't remove or rename then it'll be backward compatible. In case [we change version](https://stackoverflow.com/a/13945074) just add new properties, keep old ones even it's not used. @@ -937,7 +970,7 @@ Please note, except "tab completion" (for dotnet) part all changes would be insi * Direct/top level packages point to dependency packages. >> Could be included, down side is duplicate information, increase json size. Also I feel https://github.com/NuGet/Home/issues/11553 addresses this issue better, because in the end who transitive dependency brought in is more important than what dependencies exist under each top package. * Content hash. >> It's very easy to include it, question is how about source? Related issue https://github.com/NuGet/Home/issues/11552 -* [npm ls --json](https://gist.github.com/erdembayar/ddfbf9c160fbb8a0e31e3596f03ee906), [npm outdated -json](https://gist.github.com/erdembayar/12030f1db89ad9f2e206f2b6ff7d740f) Actually it's less sophisticated than what we have, because it doesn't have multi TFM and projects concept. +* [npm ls --json](https://gist.github.com/erdembayar/ddfbf9c160fbb8a0e31e3596f03ee906), [npm outdated -json](https://gist.github.com/erdembayar/12030f1db89ad9f2e206f2b6ff7d740f) Actually it's less sophisticated than what we have, because it doesn't have multi TFM and projects concept. In case of any error it adds it into `problems` section just as array of strings. ## Future Possibilities @@ -955,4 +988,4 @@ If we address them in plain `dotnet list package` then we'll address in `json ou * [--all option](https://github.com/NuGet/Home/issues/11551) for dotnet list package. -* Return different exit codes if any vulnerabilities, deprecations, outdated package is [detected](https://github.com/NuGet/Home/blob/dotnet-audit/proposed/2021/DotNetAudit.md#dotnet-audit-exit-codes). \ No newline at end of file +* Return [different exit codes](https://tldp.org/LDP/abs/html/exitcodes.html) if there is any error while rendering json output or if any vulnerabilities, deprecations, outdated package is [detected](https://github.com/NuGet/Home/blob/dotnet-audit/proposed/2021/DotNetAudit.md#dotnet-audit-exit-codes). It's important choose to the exit codes and provide easy ways to look up docs on each error code (see [example](https://github.com/dotnet/templating/blob/main/docs/Exit-Codes.md#106)). We could enhance `problems` section to include `errorCode` for easy lookup later. From 861ebd714d6677d8b5837033b4951459a4b3370c Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Thu, 28 Jul 2022 11:20:59 -0700 Subject: [PATCH 03/13] Address PR comment --- proposed/2022/DotnetListPackageMachineReadableJsonOutput.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index bfebbb4a20..93d4c3eecb 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -774,8 +774,7 @@ Outputs json for format version 1, if it's not specified then latest version'll ### Error handling -In case of an error it would be written into `problems` section and return non-zero error exit code to indicate there had been some error to help scripting use cases. -For current implementation we'll returns general error code `1` from application, more specific error code for each error scenario is not considered in this spec scope. +In case of an error it would be written into `problems` section and return non-0 error exit code to indicate there had been some error to help scripting use cases. In case there is parameter, options error then it may defaults back to console output instead of json output. Also in case of runtime there's error then it may not show json output at all because it needs all the data for json output before display. From 158a0bcf997e16389f8253b292f48bcff2fbca49 Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Mon, 1 Aug 2022 20:19:53 -0700 Subject: [PATCH 04/13] Add parameter/option error examples --- proposed/2022/DotnetListPackageMachineReadableJsonOutput.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index 93d4c3eecb..a53bdde114 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -775,8 +775,10 @@ Outputs json for format version 1, if it's not specified then latest version'll ### Error handling In case of an error it would be written into `problems` section and return non-0 error exit code to indicate there had been some error to help scripting use cases. -In case there is parameter, options error then it may defaults back to console output instead of json output. -Also in case of runtime there's error then it may not show json output at all because it needs all the data for json output before display. + +In case of runtime there's error then it may not show json output at all because it needs all the data for json output before display. + +In case there is parameter, options error then it may defaults back to console output instead of json output, for example: `dotnet list package -include-transitive --format json`, because that option/parameter validation for `-include-transitive` happen way before `list package` code execution. But `dotnet list package -framework net7.0` wouldn't fail even though `net7.0` is not valid framework at this moment, it would simply return empty result. #### `> dotnet list package` From db97f90dd38ce24893f444941de368bb0aef8be4 Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Tue, 27 Sep 2022 14:10:06 -0700 Subject: [PATCH 05/13] Add more cases for no vulnerable package found or found in 1 target framework. --- ...netListPackageMachineReadableJsonOutput.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index a53bdde114..479406c954 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -473,6 +473,118 @@ Project `MyProjectB` has the following vulnerable packages } ``` +#### `> dotnet list package --vulnerable` +There's no vulnerable package in a project. + +```dotnetcli +The following sources were used: + https://api.nuget.org/v3/index.json + https://apidev.nugettest.org/v3-index/index.json + +The given project `MyProjectC` has no vulnerable packages given the current sources. +``` + +### `> dotnet list package --vulnerable --format json` +There's no vulnerable package in a project. + +```json +{ + "version": 1, + "parameters": "--vulnerable", + "sources": [ + "https://api.nuget.org/v3/index.json", + "https://apidev.nugettest.org/v3-index/index.json" + ], + "projects": [ + { + "path": "src/lib/MyProjectC.csproj", + "frameworks": [ + { + "framework": "netcoreapp3.1", + "topLevelPackages": [ + ] + }, + { + "framework": "net5.0", + "topLevelPackages": [ + ] + } + ] + } + ] +} +``` + +#### `> dotnet list package --vulnerable` +For multi-target framework a project only 1 framework has a vulnerability. + +```dotnetcli +The following sources were used: + https://api.nuget.org/v3/index.json + https://apidev.nugettest.org/v3-index/index.json + +Project `MyProjectC` has the following vulnerable packages + [netcoreapp3.1]: + Top-level Package Requested Resolved Severity Advisory URL + > DotNetNuke.Core 6.0.0 6.0.0 High https://github.com/advisories/GHSA-g8j6-m4p7-5rfq + Moderate https://github.com/advisories/GHSA-v76m-f5cx-8rg4 + Critical https://github.com/advisories/GHSA-x8f7-h444-97w4 + Moderate https://github.com/advisories/GHSA-5c66-x4wm-rjfx + High https://github.com/advisories/GHSA-x2rg-fmcv-crq5 + High https://github.com/advisories/GHSA-j3g9-6fx5-gjv7 + High https://github.com/advisories/GHSA-xx3h-j3cx-8qfj + Moderate https://github.com/advisories/GHSA-5whq-j5qg-wjvp + + [net5.0]: No vulnerable packages for this framework. +``` + +### `> dotnet list package --vulnerable --format json` +For multi-target framework a project only 1 framework has a vulnerability. + +```json +{ + "version": 1, + "parameters": "--vulnerable", + "sources": [ + "https://api.nuget.org/v3/index.json", + "https://apidev.nugettest.org/v3-index/index.json" + ], + "projects": [ + { + "path": "src/lib/MyProjectC.csproj", + "frameworks": [ + { + "framework": "netcoreapp3.1", + "topLevelPackages": [ + { + "id": "DotNetNuke.Core", + "requestedVersion": "6.0.0", + "resolvedVersion": "6.0.0", + "vulnerabilities" : [ + { + "severity":"High", + "advisoryurl":"https://github.com/advisories/GHSA-g8j6-m4p7-5rfq" + }, + { + "severity":"Moderate", + "advisoryurl":"https://github.com/advisories/GHSA-v76m-f5cx-8rg4" + }, + ... + ] + } + ] + }, + { + "framework": "net5.0", + "topLevelPackages": [ + ] + } + ] + } + ] +} +``` + #### `> dotnet list package --include-transitive` ```dotnetcli From d541f4e0a2ab7c2666e4b6495b2f9c6e0b75bbe4 Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Wed, 28 Sep 2022 11:04:01 -0700 Subject: [PATCH 06/13] Add case for Given '--include-prerelease', '--highest-minor', and '--highest-patch' options are only designed to use together with --outdated argument it would output warning --- ...netListPackageMachineReadableJsonOutput.md | 39 ++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index 479406c954..648266f450 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -1029,6 +1029,43 @@ The project `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.csproj` uses packag } ``` +#### `> dotnet list package --highest-minor` + +Given '--include-prerelease', '--highest-minor', and '--highest-patch' options are only designed to use together with `--outdated` argument it would output `The command option(s) '--include-prerelease', '--highest-minor', and '--highest-patch' are ignored by this command.` warning. + +```dotnetcli +The command option(s) '--include-prerelease', '--highest-minor', and '--highest-patch' are ignored by this command. +Project 'MyProjectC' has the following package references + [netcoreapp3.1]: + Top-level Package Requested Resolved + > DotNetNuke.Core 6.0.0 6.0.0 + > Newtonsoft.Json 13.0.1 13.0.1 + + [net5.0]: No packages were found for this framework. +``` + +#### `> dotnet list package --highest-minor --format json` + +Json output for above case. + +```json +{ + "version": 1, + "parameters": "--highest-minor", + "problems": [ + { + "message": "The command option(s) '--include-prerelease', '--highest-minor', and '--highest-patch' are ignored by this command." + } + ], + "projects": [ + { + "path": "src/lib/MyProjectC.csproj", + ... + } + ] +} +``` + #### `> dotnet list package --format json --output-version 3` Since output version `3` is not available, then it'll default to latest available version, and log about unsupported format version request into json result. @@ -1036,7 +1073,7 @@ Since output version `3` is not available, then it'll default to latest availabl ```json { "version": 1, - "parameters": "", + "parameters": "--output-version 3", "problems": [ { "message": "Unsupported output format version 3 was requested. Defaulting to latest available format version 1." From c30f2862f26fe95421cc830f636c0e0473ce181d Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Thu, 29 Sep 2022 11:59:38 -0700 Subject: [PATCH 07/13] Add more explicit example on complex scenario: dotnet list package --vulnerable --include-transitive --- ...netListPackageMachineReadableJsonOutput.md | 98 ++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index 648266f450..d4470f9845 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -867,6 +867,102 @@ Project `MyProjectB` has the following deprecated packages } ``` +#### `> dotnet list package --vulnerable --include-transitive` +For multi-target framework a project only 1 framework has a vulnerability. + +```dotnetcli +The following sources were used: + https://api.nuget.org/v3/index.json + +Project `MyProjectE` has the following vulnerable packages + [netcoreapp3.1]: + Top-level Package Requested Resolved Severity Advisory URL + > DotNetNuke.Core 6.0.0 6.0.0 High https://github.com/advisories/GHSA-g8j6-m4p7-5rfq + Moderate https://github.com/advisories/GHSA-v76m-f5cx-8rg4 + Critical https://github.com/advisories/GHSA-x8f7-h444-97w4 + Moderate https://github.com/advisories/GHSA-5c66-x4wm-rjfx + High https://github.com/advisories/GHSA-x2rg-fmcv-crq5 + High https://github.com/advisories/GHSA-j3g9-6fx5-gjv7 + High https://github.com/advisories/GHSA-xx3h-j3cx-8qfj + Moderate https://github.com/advisories/GHSA-5whq-j5qg-wjvp + > NuGet.Commands 4.8.0-preview3.5278 4.8.0-preview3.5278 Moderate https://github.com/advisories/GHSA-3885-8gqc-3wpf + + Transitive Package Resolved Severity Advisory URL + > Newtonsoft.Json 9.0.1 High https://github.com/advisories/GHSA-5crp-9r3c-p9vr + > System.Net.Http 4.3.0 High https://github.com/advisories/GHSA-7jgj-8wvc-jh57 + > System.Text.RegularExpressions 4.3.0 Moderate https://github.com/advisories/GHSA-cmhx-cq75-c4mj +``` + +### `> dotnet list package --vulnerable --include-transitive --format json` +For multi-target framework a project only 1 framework has a vulnerability. + +```json +{ + "version": 1, + "parameters": "--vulnerable", + "sources": [ + "https://api.nuget.org/v3/index.json", + "https://apidev.nugettest.org/v3-index/index.json" + ], + "projects": [ + { + "path": "src/lib/MyProjectC.csproj", + "frameworks": [ + { + "framework": "netcoreapp3.1", + "topLevelPackages": [ + { + "id": "DotNetNuke.Core", + "requestedVersion": "6.0.0", + "resolvedVersion": "6.0.0", + "vulnerabilities" : [ + { + "severity":"High", + "advisoryurl":"https://github.com/advisories/GHSA-g8j6-m4p7-5rfq" + }, + { + "severity":"Moderate", + "advisoryurl":"https://github.com/advisories/GHSA-v76m-f5cx-8rg4" + }, + ... + ] + } + ], + "transitivePackages": [ + { + "id": "Newtonsoft.Json", + "resolvedVersion": "9.0.1", + "vulnerabilities" : [ + { + "severity":"High", + "advisoryurl":"https://github.com/advisories/GHSA-5crp-9r3c-p9vr" + } + ] + }, + { + "id": "System.Net.Http", + "resolvedVersion": "4.3.0", + "vulnerabilities" : [ + { + "severity":"High", + "advisoryurl":"https://github.com/advisories/GHSA-7jgj-8wvc-jh57" + } + ] + } + ... + ] + }, + { + "framework": "net5.0", + "topLevelPackages": [ + ] + } + ] + } + ] +} +``` + #### `> dotnet list package --format json --output-version 1` Outputs json for format version 1, if it's not specified then latest version'll be used by default. @@ -915,7 +1011,7 @@ No assets file was found for `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.cs "parameters": "", "problems": [ { - "project": "src/lib/MyProjectA.csproj", + "project": "src/lib/MyProjectB.csproj", "message": "No assets file was found for `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`. Please run restore before running this command." } ], From c47a52a4a14d76418b7728a3fb7ac8a0f03a89c6 Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Wed, 12 Oct 2022 19:40:59 -0700 Subject: [PATCH 08/13] Add autoreferenced package example --- ...netListPackageMachineReadableJsonOutput.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index d4470f9845..728dda7ac0 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -141,6 +141,46 @@ Project 'MyProjectB' has the following package references } ``` +#### `> dotnet list package` +Project with an auto-referenced package. + +```dotnetcli +Project 'MyProjectF' has the following package references + [netstandard2.0]: + Top-level Package Requested Resolved + > NETStandard.Library (A) [2.0.3, ) 2.0.3 + +(A) : Auto-referenced package. +``` + +#### `> dotnet list package --format json` +Project with an auto-referenced package. + +```json +{ + "version": 1, + "parameters": "", + "projects": [ + { + "path": "src/lib/MyProjectF.csproj", + "frameworks": [ + { + "framework": "netstandard2.0", + "topLevelPackages": [ + { + "id": "NETStandard.Library", + "requestedVersion": "[2.0.3, )", + "resolvedVersion": "2.0.3", + "autoReferenced": "true" + } + ] + } + ] + } + ] +} +``` + #### `> dotnet list package --outdated` ```dotnetcli From f82e58cb979526c43f79caed8c286d2113437951 Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Tue, 18 Oct 2022 14:13:47 -0700 Subject: [PATCH 09/13] Add http source warning --- ...netListPackageMachineReadableJsonOutput.md | 37 ++++++++++++++++--- 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index 728dda7ac0..945df55666 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -1052,7 +1052,7 @@ No assets file was found for `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.cs "problems": [ { "project": "src/lib/MyProjectB.csproj", - "message": "No assets file was found for `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`. Please run restore before running this command." + "error": "No assets file was found for `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`. Please run restore before running this command." } ], "projects": [ @@ -1102,7 +1102,7 @@ Could not find file or directory 'C:\Users\userA\repos\MainApp\src\lib\NonExisti "problems": [ { "project": "src/lib/NonExisting.csproj", - "message": "Could not find file or directory 'C:/Users/userA/repos/MainApp/src/lib/NonExisting.csproj'" + "error": "Could not find file or directory 'C:/Users/userA/repos/MainApp/src/lib/NonExisting.csproj'" } ] } @@ -1132,7 +1132,7 @@ The project `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.csproj` uses packag "problems": [ { "project": "src/lib/MyProjectB.csproj", - "message": "The project `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`` uses package.config for NuGet packages, while the command works only with package reference projects." + "error": "The project `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`` uses package.config for NuGet packages, while the command works only with package reference projects." } ], "projects": [ @@ -1190,14 +1190,39 @@ Json output for above case. "parameters": "--highest-minor", "problems": [ { - "message": "The command option(s) '--include-prerelease', '--highest-minor', and '--highest-patch' are ignored by this command." + "warning": "The command option(s) '--include-prerelease', '--highest-minor', and '--highest-patch' are ignored by this command." } ], "projects": [ + ] +} +``` + +#### `> dotnet list package --vulnerable` + +Warning for `Http source used` in printed. + +```dotnetcli +The following sources were used: + http://apidev.nugettest.org/v3-index/index.json + +warn : You are running the 'list package' operation with an 'HTTP' source, 'nugettest [http://apidev.nugettest.org/v3-index/index.json]'. Non-HTTPS access will be removed in a future version. Consider migrating to an 'HTTPS' source. +``` + +#### `> dotnet list package --vulnerable --format json` + +Warning for `Http source used` is included in json. + +```json +{ + "version": 1, + "parameters": "--vulnerable", + "problems": [ { - "path": "src/lib/MyProjectC.csproj", - ... + "warning": "You are running the 'list package' operation with an 'HTTP' source, 'nugettest [http://apidev.nugettest.org/v3-index/index.json]'. Non-HTTPS access will be removed in a future version. Consider migrating to an 'HTTPS' source." } + ], + "projects": [ ] } ``` From 86ef63a7d70c68c8813115f99d028fdeb6c8dde8 Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Tue, 18 Oct 2022 16:28:01 -0700 Subject: [PATCH 10/13] Add error/warning summary table --- ...netListPackageMachineReadableJsonOutput.md | 24 +++++++++++++------ 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index 945df55666..b575bf88d9 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -1020,13 +1020,23 @@ Outputs json for format version 1, if it's not specified then latest version'll } ``` -### Error handling - -In case of an error it would be written into `problems` section and return non-0 error exit code to indicate there had been some error to help scripting use cases. - -In case of runtime there's error then it may not show json output at all because it needs all the data for json output before display. - -In case there is parameter, options error then it may defaults back to console output instead of json output, for example: `dotnet list package -include-transitive --format json`, because that option/parameter validation for `-include-transitive` happen way before `list package` code execution. But `dotnet list package -framework net7.0` wouldn't fail even though `net7.0` is not valid framework at this moment, it would simply return empty result. +### Error/Warning handling + +In case of an `error` it would be written into `problems` section and return non-0 error exit code if there is any `error` to indicate there had been some error to help scripting use case. Note: `Warnings` in `problems` section are not considered as `error`. + +| # | Scenario | Behavior in dotnet cli | Exit code +|---|---|---|---| +| 1 | Missing .net sdk/runtime installion| No json output, show missing .net sdk/runtime installation error in console | ? +| 1 | Runtime error | No json output, because it needs all the data for json output, normal error stack output in console| 1 +| 1 | Parameter/options typo error | May defaults back to console output instead of json output, for example: `dotnet list package -include-transitive --format json` (here `-include-transitive` is missing another `-` in front), because that option/parameter validation for `-include-transitive` happen way before `list package` code execution | 1 +| 1 | Passing unsupported targetframe | `dotnet list package -framework net9.0` wouldn't fail even though `net9.0` is not valid framework at this moment, it would simply return empty result. | 0 +| 1 | Asset file missing | Error would be in problems section of json, see below. | 1 +| 1 | Non-existing csproj file path | Error would be in problems section of json, see below. | 1 +| 1 | Package.config project | Error would be in problems section of json, see below. | 1 +| 1 | Incompatible option combination | Warning would be in problems section of json, see below. | 0 +| 1 | Use of not secure http source | Warning would be in problems section of json, see below. | 0 +| 1 | Unsupported output format | Defaults back to console output, for example: `dotnet list package --format yaml` | 1 +| 1 | Unsupported output version | Warning would be in problems section of json, defaults to latest supported version 1, see below. | 0 #### `> dotnet list package` From 5819955f0d7eaafad498e69781d08c3492225e7e Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Thu, 27 Oct 2022 11:40:14 -0700 Subject: [PATCH 11/13] Error out on unsupported version value --- ...netListPackageMachineReadableJsonOutput.md | 31 ++++++++----------- 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index b575bf88d9..557c3fb6e7 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -1036,7 +1036,8 @@ In case of an `error` it would be written into `problems` section and return non | 1 | Incompatible option combination | Warning would be in problems section of json, see below. | 0 | 1 | Use of not secure http source | Warning would be in problems section of json, see below. | 0 | 1 | Unsupported output format | Defaults back to console output, for example: `dotnet list package --format yaml` | 1 -| 1 | Unsupported output version | Warning would be in problems section of json, defaults to latest supported version 1, see below. | 0 +| 1 | Unsupported output version | if it's for json output then no json output, error out unsupported output version , see below | 1 +| 1 | Unsupported output version | if it's for console output then it's ignored, versioning is not considered for console output | 0 #### `> dotnet list package` @@ -1237,26 +1238,20 @@ Warning for `Http source used` is included in json. } ``` +#### `> dotnet list package --format yaml` + +Output format yaml is not supported, error out. + +```dotnetcli +error: Invalid value yaml provided for output format. The accepted values are console, json. +``` + #### `> dotnet list package --format json --output-version 3` -Since output version `3` is not available, then it'll default to latest available version, and log about unsupported format version request into json result. +Output version `3` is not supported, error out instead of defaulting to any version, because defaulting to any version might give false negative which hides actual serious issue in report details. -```json -{ - "version": 1, - "parameters": "--output-version 3", - "problems": [ - { - "message": "Unsupported output format version 3 was requested. Defaulting to latest available format version 1." - } - ], - "projects": [ - { - "path": "src/lib/MyProjectA.csproj", - ... - } - ] -} +```dotnetcli +error: Unsupported output format version 3 was requested. The accepted format version value is 1. ``` ## Compatibility From 557f5dfdcdaf21f7a83dab6d30a35d05d33d489b Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Mon, 31 Oct 2022 21:44:30 -0700 Subject: [PATCH 12/13] Add level property into problems --- .../DotnetListPackageMachineReadableJsonOutput.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index 557c3fb6e7..1a8c7c996b 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -1062,8 +1062,9 @@ No assets file was found for `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.cs "parameters": "", "problems": [ { + "level" : "error", "project": "src/lib/MyProjectB.csproj", - "error": "No assets file was found for `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`. Please run restore before running this command." + "text": "No assets file was found for `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`. Please run restore before running this command." } ], "projects": [ @@ -1112,8 +1113,9 @@ Could not find file or directory 'C:\Users\userA\repos\MainApp\src\lib\NonExisti "parameters": "", "problems": [ { + "level" : "error", "project": "src/lib/NonExisting.csproj", - "error": "Could not find file or directory 'C:/Users/userA/repos/MainApp/src/lib/NonExisting.csproj'" + "text": "Could not find file or directory 'C:/Users/userA/repos/MainApp/src/lib/NonExisting.csproj'" } ] } @@ -1142,8 +1144,9 @@ The project `C:\Users\userA\repos\MainApp\src\lib\MyProjectB.csproj` uses packag "parameters": "", "problems": [ { + "level" : "error", "project": "src/lib/MyProjectB.csproj", - "error": "The project `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`` uses package.config for NuGet packages, while the command works only with package reference projects." + "text": "The project `C:/Users/userA/repos/MainApp/src/lib/MyProjectB.csproj`` uses package.config for NuGet packages, while the command works only with package reference projects." } ], "projects": [ @@ -1201,7 +1204,8 @@ Json output for above case. "parameters": "--highest-minor", "problems": [ { - "warning": "The command option(s) '--include-prerelease', '--highest-minor', and '--highest-patch' are ignored by this command." + "level" : "warning", + "text": "The command option(s) '--include-prerelease', '--highest-minor', and '--highest-patch' are ignored by this command." } ], "projects": [ @@ -1230,7 +1234,8 @@ Warning for `Http source used` is included in json. "parameters": "--vulnerable", "problems": [ { - "warning": "You are running the 'list package' operation with an 'HTTP' source, 'nugettest [http://apidev.nugettest.org/v3-index/index.json]'. Non-HTTPS access will be removed in a future version. Consider migrating to an 'HTTPS' source." + "level" : "warning", + "text": "You are running the 'list package' operation with an 'HTTP' source, 'nugettest [http://apidev.nugettest.org/v3-index/index.json]'. Non-HTTPS access will be removed in a future version. Consider migrating to an 'HTTPS' source." } ], "projects": [ From 04b3ebec7868c09054f800af8996148e4e3b15c8 Mon Sep 17 00:00:00 2001 From: Erick Yondon Date: Fri, 4 Nov 2022 09:29:07 -0700 Subject: [PATCH 13/13] Unsupported version error out on console output --- .../2022/DotnetListPackageMachineReadableJsonOutput.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md index 1a8c7c996b..d3d0cad04b 100644 --- a/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md +++ b/proposed/2022/DotnetListPackageMachineReadableJsonOutput.md @@ -1037,7 +1037,7 @@ In case of an `error` it would be written into `problems` section and return non | 1 | Use of not secure http source | Warning would be in problems section of json, see below. | 0 | 1 | Unsupported output format | Defaults back to console output, for example: `dotnet list package --format yaml` | 1 | 1 | Unsupported output version | if it's for json output then no json output, error out unsupported output version , see below | 1 -| 1 | Unsupported output version | if it's for console output then it's ignored, versioning is not considered for console output | 0 +| 1 | Unsupported output version | if it's for console output then error out unsupported output version , see below | 1 #### `> dotnet list package` @@ -1259,6 +1259,14 @@ Output version `3` is not supported, error out instead of defaulting to any vers error: Unsupported output format version 3 was requested. The accepted format version value is 1. ``` +#### `> dotnet list package --format console --output-version 3` + +Output version `3` is not supported, error out instead of defaulting to any version, because defaulting to any version might give false negative which hides actual serious issue in report details. + +```dotnetcli +error: Unsupported output format version 3 was requested. The accepted format version value is 1. +``` + ## Compatibility We start with `version 1`, as long as we don't remove or rename then it'll be backward compatible. In case [we change version](https://stackoverflow.com/a/13945074) just add new properties, keep old ones even it's not used.