FEATURE: enable --report for preview (not just push) (#3149)

Co-authored-by: Jeffrey Cafferata <jeffrey@jcid.nl>

commands/ppreviewPush.go

@@ -50,6 +50,7 @@ type PPreviewArgs struct {
 	ConcurMode  string
 	NoPopulate  bool
 	DePopulate  bool
+	Report      string
 	Full        bool
 }
 
@@ -116,6 +117,11 @@ func (args *PPreviewArgs) flags() []cli.Flag {
 		Destination: &bindserial.ForcedValue,
 		Usage:       `Force BIND serial numbers to this value (for reproducibility)`,
 	})
+	flags = append(flags, &cli.StringFlag{
+		Name:        "report",
+		Destination: &args.Report,
+		Usage:       `Generate a machine-parseable report of corrections.`,
+	})
 	return flags
 }
 
@@ -135,7 +141,6 @@ var _ = cmd(catMain, func() *cli.Command {
 type PPushArgs struct {
 	PPreviewArgs
 	Interactive bool
-	Report      string
 }
 
 func (args *PPushArgs) flags() []cli.Flag {
@@ -145,17 +150,12 @@ func (args *PPushArgs) flags() []cli.Flag {
 		Destination: &args.Interactive,
 		Usage:       "Interactive. Confirm or Exclude each correction before they run",
 	})
-	flags = append(flags, &cli.StringFlag{
-		Name:        "report",
-		Destination: &args.Report,
-		Usage:       `Generate a machine-parseable report of performed corrections.`,
-	})
 	return flags
 }
 
 // PPreview implements the preview subcommand.
 func PPreview(args PPreviewArgs) error {
-	return prun(args, false, false, printer.DefaultPrinter, "")
+	return prun(args, false, false, printer.DefaultPrinter, args.Report)
 }
 
 // PPush implements the push subcommand.

commands/previewPush.go

@@ -44,6 +44,7 @@ type PreviewArgs struct {
 	WarnChanges bool
 	NoPopulate  bool
 	Full        bool
+	Report      string
 }
 
 // ReportItem is a record of corrections for a particular domain/provider/registrar.
@@ -92,6 +93,11 @@ func (args *PreviewArgs) flags() []cli.Flag {
 		Destination: &bindserial.ForcedValue,
 		Usage:       `Force BIND serial numbers to this value (for reproducibility)`,
 	})
+	flags = append(flags, &cli.StringFlag{
+		Name:        "report",
+		Destination: &args.Report,
+		Usage:       `Generate a machine-parseable report of corrections counts.`,
+	})
 	return flags
 }
 
@@ -111,7 +117,6 @@ var _ = cmd(catMain, func() *cli.Command {
 type PushArgs struct {
 	PreviewArgs
 	Interactive bool
-	Report      string
 }
 
 func (args *PushArgs) flags() []cli.Flag {
@@ -121,17 +126,12 @@ func (args *PushArgs) flags() []cli.Flag {
 		Destination: &args.Interactive,
 		Usage:       "Interactive. Confirm or Exclude each correction before they run",
 	})
-	flags = append(flags, &cli.StringFlag{
-		Name:        "report",
-		Destination: &args.Report,
-		Usage:       `Generate a machine-parseable report of performed corrections.`,
-	})
 	return flags
 }
 
 // Preview implements the preview subcommand.
 func Preview(args PreviewArgs) error {
-	return run(args, false, false, printer.DefaultPrinter, nil)
+	return run(args, false, false, printer.DefaultPrinter, &args.Report)
 }
 
 // Push implements the push subcommand.

documentation/json-reports.md

@@ -1,10 +1,21 @@
 # JSON Reports
 
-DNSControl has build in functionality to generate a machine-parseable report after pushing changes. This report is JSON formated and contains the zonename, the provider or registrar name and the amount of performed changes.
+DNSControl can generate a machine-parseable report of changes.
 
-## Usage
+The report is JSON formated and contains the zonename, the provider or
+registrar name, and the number of changes.
 
-To enable the report option you must use the `push` operation in combination with the `--report <filename>` option. This generates the json file.
+To generate the report, add the `--report <filename>` option to a preview or
+push command (this includes `preview`, `ppreview`, `push`,
+`ppush`).
+
+
+The report lists the changes that would be (preview) or are (push) attempted,
+whether they are successful or not.
+
+If a fatal error happens during the run, no report is generated.
+
+## Sample output
 
 {% code title="report.json" %}
 ```json

documentation/preview-push.md

@@ -26,7 +26,7 @@ OPTIONS:
    --no-populate                                              Use this flag to not auto-create non-existing zones at the provider (default: false)
    --full                                                     Add headings, providers names, notifications of no changes, etc (default: false)
    --bindserial value                                         Force BIND serial numbers to this value (for reproducibility) (default: 0)
-   --report value                                             (push) Generate a JSON-formatted report of the number of changes made.
+   --report value                                             Generate a JSON-formatted report of the number of changes.
    --help, -h                                                 show help
 ```
 
@@ -92,9 +92,9 @@ OPTIONS:
     generally used for reproducibility in testing pipelines.
 
 * `--report name`
-  * (`push` only!)  Generate a machine-parseable report of
-    performed corrections in the file named `name`. If no name is specified, no
-    report is generated.
+  * Write a machine-parseable report of
+    corrections to the file named `name`. If no name is specified, no
+    report is generated. See [JSON Reports](json-reports.md)
 
 ## ppreview/ppush