SE-0501: Update proposal base on review

Update the SE-0501 proposal based on feedback from the review

Author: bkhouri

proposals/0501-swiftpm-html-coverage-report.md

@@ -5,7 +5,7 @@
 * Review Manager: [David Cummings](https://github.com/daveyc123)
 * Status: **Active Review (December 7 - December 22, 2025)**
 * Implementation: [swiftlang/swift-package-manager#9076](https://github.com/swiftlang/swift-package-manager/pull/9076)
-* Review: 
+* Review:
     * [Pitch](https://forums.swift.org/t/pitch-adding-html-coverage-support/82358)
     * [Review](https://forums.swift.org/t/se-0501-html-coverage-report/83601/1)
 
@@ -70,6 +70,30 @@ make use of LLVM's tools and construct the proper command line arguments to the
 
 The proposted command line changes are as follows:
 
+### Consolidate coverage option to use same argument "style"
+
+Prior to this feature, there are 2 coverage options
+
+```
+  --show-codecov-path, --show-code-coverage-path, --show-coverage-path
+                          Print the path of the exported code coverage JSON
+  --enable-code-coverage/--disable-code-coverage
+                          Enable code coverage. (default:
+                          --disable-code-coverage)
+```
+
+There are 3 wayt to  show the coverage path.  This proposal recommends modify all
+coverage command line option to be a single, more useful option
+
+```
+  --show-coverage-path
+                          Print the path of the exported code coverage JSON
+  --enable-coverage/--disable-coverage
+                          Enable code coverage. (default:
+                          --disable-coverage)
+```
+
+This requires gracefully phasing out the previous option in favour of the new one.
 
 ### Format Selection
 
@@ -81,7 +105,7 @@ specified.
 The command line option will be similar to:
 
 ```sh
-  --codecov-format, --code-coverage-format, --coverage-format <format>
+  --coverage-format <format>
                           Format of the code coverage output. Can be specified multiple times. (default: json)
         json              - Produces a JSON coverage report.
         html              - Produces an HTML report produced by llvm-cov.
@@ -93,8 +117,9 @@ The command line option will be similar to:
 `llvm-cov show` has several report configurability options. In order to
 prevent a "command line arguments" explosion to `swift test`, the configuration
 options will be read from a response file.  The optional response file will be
-located in `<repo>/.swiftpm/configuration/coverage.html.report.args.txt`.  The
-response file will be supported.
+located in `<repo>/.swiftpm/configuration/coverage.html.report.args.txt`, which
+is the same location used by other SwiftPM features, such as registration and
+mirros configuration files.  The response file will be supported.
 
 The user can include `--format=text`, or a variation thereof, in the response
 file. In order to ensure SwiftPM will always generate an HTML report, SwiftPM
@@ -116,15 +141,14 @@ assumption that the CI system will have a copy of the repository in the "sandbox
 location, allowing this system to upload the HTML report.
 
 ```
-  --show-codecov-path [mode], --show-code-coverage-path  [mode], --show-coverage-path  [mode]
+  --show-coverage-path  [mode]
                           Print the path of the exported code coverage files.  The mode specifies how to
                           display the paths of the selected code coverage file formats. (default: text)
         json              - Display the output in JSON format.
         text              - Display the output as plain text.
-  --show-codecov-path-mode, --show-code-coverage-path-mode, --show-coverage-path-mode <show-codecov-path-mode>
-  --enable-codecov, --enable-code-coverage, --enable-coverage/--disable-codecov, --disable-code-coverage, --disable-coverage
+   --enable-coverage/--disable-coverage
                           Enable code coverage. (default: --disable-codecov)
-  --codecov-format, --code-coverage-format, --coverage-format <format>
+  --coverage-format <format>
                           Format of the code coverage output. Can be specified multiple times. (values: json, html; default: Produces a JSON coverage report.)
 ```
 
@@ -191,17 +215,36 @@ No impact is expected.
 
 ## Alternatives considered
 
-- In addition to the response file, the coverage report generation can support
-  a command line argument similar to `-Xlinker`, `-Xcc` and others, which will
-  pass the arguments to `llvm-cov show` and override the values in the response
-  file. This has _not_ been implemented in the [PR].
 
-- Instead of having a `--show-codecov-path` as a tri-state, we could preserve
-  `--show-codecov-path` original behaviour and add an additional command line
-  argument to indicate the output mode.  The comand line argument would be
-  `--show-codecov-path-mode <mode>`, where `<mode>` is either `text` or `json`.
-  This was not favours as `--show-codecov-path-mode` would have a dependency on
-  `--show-codecov-path` argument, and may lead to some confusion.
+### Using `-Xcov`-style argument
+
+In addition to the response file, the coverage report generation can support
+a command line argument similar to `-Xlinker`, `-Xcc` and others, which will
+pass the arguments to `llvm-cov show` and override the values in the response
+file.
+
+Once benefit of having a response file in the repository is the ability of
+generating a repeatable HTML report.  In addition, since `llvm-cov` has many
+subcommands, we would need careful considering on how to handle the case where
+we demand JSON and HTML report, but the associated `llvm-cov`  subcommand does
+not support all the `-Xcov` arguments provided via the `swift test` command line
+option.
+
+The intent is that when demand an HTML coverage report, the same HTML report is
+produced for all users. Granted, this does not prevent a user from modifying the
+response file arguments and create a "temporary HTML" report, but the repository
+will be the source of truth for these HTML report command options.
+
+As a result, it was decided to only support a response file, where said response
+file is in a given location relative to the repository root.
+
+Support for `-Xcov` (or similar) is to be made in a subsequent proposal.
 
+### `--show-coverage-path` alternative
 
-[PR]: https://github.com/swiftlang/swift-package-manager/pull/9076
+Instead of having a `--show-coverage-path` as a tri-state, we could preserve
+`--show-coverage-path` original behaviour and add an additional command line
+argument to indicate the output mode.  The comand line argument would be
+`--show-coverage-path-mode <mode>`, where `<mode>` is either `text` or `json`.
+This was not favoured as `--show-coverage-path-mode` would have a dependency on
+`--show-coverage-path` argument, and may lead to some confusion.