feat(site): add docs for the report command

site/docs/src/SUMMARY.md

@@ -7,4 +7,5 @@
     - [normalizer transform](./commands/normalizer-transform.md)
     - [normalizer dataize](./commands/normalizer-dataize.md)
     - [normalizer metrics](./commands/normalizer-metrics.md)
+    - [normalizer report](./commands/normalizer-report.md)
 - [Contributing](./contributing.md)

site/docs/src/commands/normalizer-report.md

@@ -0,0 +1,100 @@
+# normalizer report
+
+## Reports
+
+The `report` command generates reports about initial and normalized `PHI` programs.
+
+The reports contain detailed information about metrics collected for these programs.
+
+The reports are in `HTML`, `GitHub Flavored Markdown`, and `JSON` formats.
+
+## Environment
+
+The command requires that there are:
+
+- Initial `PHI` programs
+- Normalized `PHI` programs
+- A report configuration file
+
+### `PHI` programs
+
+Currently, we translate `EO` programs and get initial `PHI` programs.
+
+Next, we normalize these `PHI` programs and get normalized `PHI` programs.
+
+### Report configuration file
+
+The report configuration file has several attributes:
+
+- `input`
+  - `js` - Optional path to a `JavaScript` file that should be inlined into an `HTML` report.
+    - If no path is specified, `normalizer` will use `report/main.js` from the `eo-phi-normalizer` package.
+  - `css` - Optional path to a `CSS` file that should be inlined into an `HTML` report.
+    - If no path is specified, `normalizer` will use `report/styles.css` from the `eo-phi-normalizer` package.
+- `output`
+  - `html` - Optional path to an `HTML` report.
+    - If no path is specified, the `HTML` report won't be generated.
+  - `json` - Optional path to a `JSON` report.
+    - If no path is specified, the `JSON` report won't be generated.
+  - `markdown` - Optional path to a `GitHub Flavored Markdown` report.
+    - If no path is specified, the `GitHub Flavored Markdown` report won't be generated.
+- `expected-metrics-change` - Specifies expected changes of metrics for normalized `PHI` programs relative to the initial `PHI` programs. Values represent `(metric_initial - metric_normalized) / metric_ initial`. Attributes:
+  - `dataless`
+  - `applications`
+  - `formations`
+  - `dispatches`
+- `items`
+  - `phi` - path to an initial `PHI` program.
+  - `phi-normalized` - path to a normalized `PHI` program.
+    - The normalized `PHI` program should correspond to the initial `PHI` program.
+  - `bindings-path-phi` - path to bindings of a formation in the initial `PHI` program.
+    - `org.eolang` corresponds to a formation `Φ.org.eolang`.
+  - `bindings-path-phi-normalized` - path to bindings of a formation in the normalized `PHI` program.
+    - `org.eolang` corresponds to a formation `Φ.org.eolang`.
+
+#### Sample report configuration file
+
+The `normalizer` repository contains the `report/config.yaml` report configuration file.
+
+<details>
+
+<summary>Click to view the file</summary>
+
+```yaml
+{{#include ../../../../report/config.yaml}}
+```
+
+</details>
+
+## CLI
+
+### `--help`
+
+```$ as console
+normalizer report --help
+```
+
+```console
+Usage: normalizer report (-c|--config FILE)
+
+  Generate reports about initial and normalized PHI programs.
+
+Available options:
+  -c,--config FILE         The FILE with a report configuration.
+  -h,--help                Show this help text
+```
+
+### `--config`
+
+Generate reports using a configuration file `report/config.yaml`.
+
+```$ as console
+normalizer report --config report/config.yaml
+ls report/report*
+```
+
+```console
+report/report.html
+report/report.json
+report/report.md
+```