feat(docs): name the boolean type in the flag table

pflag.UnquoteUsage returns an empty type name for booleans, so 403 of the 1546
flag rows had a blank cell in a column headed Type. That reads as missing data
and left the reader to infer that the flag takes no value. Fall back to the
underlying pflag type name, so a boolean says bool.

The fallback is on the empty string rather than on the bool type specifically,
so any future pflag type that declines to name itself is covered too. It runs
before the NoOptDefVal block, so an optional value reads as bool[=x], matching
the existing string[="x"].

Regenerated all 94 command docs: no cell is empty now, every row is still a
well formed three column row, and comparing against the previous output, 403
rows had an empty type become bool while the other 1143 are untouched. No flag
name or description changed anywhere.

Author: mbevc1

cmd/kosli/testdata/output/docs/mintlify/artifact.md

@@ -51,12 +51,12 @@ is set), registry credentials are resolved as follows:
 | `-t`, `--artifact-type` | string | The type of the artifact to calculate its SHA256 fingerprint. One of: [oci, docker, file, dir]. Only required if you want Kosli to calculate the fingerprint for you (i.e. when you don't specify '`--fingerprint`' on commands that allow it). |
 | `-b`, `--build-url` | string | The url of CI pipeline that built the artifact. (defaulted in some CIs: [docs](/integrations/ci_cd) ). |
 | `-u`, `--commit-url` | string | The url for the git commit that created the artifact. (defaulted in some CIs: [docs](/integrations/ci_cd) ). |
-| `-D`, `--dry-run` |  | [optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors. |
+| `-D`, `--dry-run` | bool | [optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors. |
 | `-x`, `--exclude` | strings | [optional] The comma separated list of directories and files to exclude from fingerprinting. Can take glob patterns. Only applicable for `--artifact-type` dir. |
 | `-F`, `--fingerprint` | string | [conditional] The SHA256 fingerprint of the artifact. Only required if you don't specify '`--artifact-type`'. |
 | `-f`, `--flow` | string | The Kosli flow name. |
 | `-g`, `--git-commit` | string | [defaulted] The git commit from which the artifact was created. (defaulted in some CIs: [docs](/integrations/ci_cd), otherwise defaults to HEAD ). |
-| `-h`, `--help` |  | help for artifact |
+| `-h`, `--help` | bool | help for artifact |
 | `-n`, `--name` | string | [optional] Artifact display name, if different from file, image or directory name. |
 | `--registry-password` | string | [conditional] The container registry password or access token. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper. |
 | `--registry-provider` | string | [deprecated] The docker registry provider or url. Only required if you want to read docker image SHA256 digest from a remote docker registry. (DEPRECATED: no longer used) |

cmd/kosli/testdata/output/docs/mintlify/snyk.md

@@ -40,13 +40,13 @@ In other CI systems, set them explicitly to capture repository metadata.
 | `--attachments` | strings | [optional] The comma-separated list of paths of attachments for the reported attestation. Attachments can be files or directories. All attachments are compressed and uploaded to Kosli's evidence vault. |
 | `-g`, `--commit` | string | [conditional] The git commit for which the attestation is associated to. Becomes required when reporting an attestation for an artifact before reporting it to Kosli. (defaulted in some CIs: [docs](/integrations/ci_cd) ). |
 | `--description` | string | [optional] attestation description |
-| `-D`, `--dry-run` |  | [optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors. |
+| `-D`, `--dry-run` | bool | [optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors. |
 | `-x`, `--exclude` | strings | [optional] The comma separated list of directories and files to exclude from fingerprinting. Can take glob patterns. Only applicable for `--artifact-type` dir. |
 | `--external-fingerprint` | stringToString | [optional] A SHA256 fingerprint of an external attachment represented by `--external-url`. The format is label=fingerprint (labels cannot contain '.' or '='). This flag can be set multiple times. There must be an external url with a matching label for each external fingerprint. |
 | `--external-url` | stringToString | [optional] Add labeled reference URL for an external resource. The format is label=url (labels cannot contain '.' or '='). This flag can be set multiple times. If the resource is a file or dir, you can optionally add its fingerprint via `--external-fingerprint` |
 | `-F`, `--fingerprint` | string | [conditional] The SHA256 fingerprint of the artifact to attach the attestation to. Only required if the attestation is for an artifact and `--artifact-type` and artifact name/path are not used. |
 | `-f`, `--flow` | string | The Kosli flow name. |
-| `-h`, `--help` |  | help for snyk |
+| `-h`, `--help` | bool | help for snyk |
 | `-n`, `--name` | string | The name of the attestation as declared in the flow or trail yaml template. |
 | `-o`, `--origin-url` | string | [optional] The url pointing to where the attestation came from or is related. (defaulted to the CI url in some CIs: [docs](/integrations/ci_cd/#defaulted-kosli-command-flags-from-ci-variables) ). |
 | `--redact-commit-info` | strings | [optional] The list of commit info to be redacted before sending to Kosli. Allowed values are one or more of [author, message, branch]. |
@@ -60,7 +60,7 @@ In other CI systems, set them explicitly to capture repository metadata.
 | `--repository` | string | [conditional] The name of the repository (e.g. owner/repo-name). All three of `--repo-id`, `--repo-url` and `--repository` must be set to record repository information (defaulted in some CIs: [docs](/integrations/ci_cd) ). |
 | `-R`, `--scan-results` | string | The path to Snyk scan SARIF results file from 'snyk test' and 'snyk container test'. By default, the Snyk results will be uploaded to Kosli's evidence vault. |
 | `-T`, `--trail` | string | The Kosli trail name. |
-| `--upload-results` |  | [defaulted] Whether to upload the provided Snyk results file as an attachment to Kosli or not. (default true) |
+| `--upload-results` | bool | [defaulted] Whether to upload the provided Snyk results file as an attachment to Kosli or not. (default true) |
 | `-u`, `--user-data` | string | [optional] The path to a JSON file containing additional data you would like to attach to the attestation. |
 
 

internal/docgen/helpers.go

@@ -53,10 +53,15 @@ func CommandsInTable(f *pflag.FlagSet) string {
 			flagName = "--" + flag.Name
 		}
 
-		// varname is the value type ("string", "strings", ...) and is empty for
-		// booleans. NoOptDefVal describes the optional-value syntax, so it is
-		// appended here rather than to the description.
+		// varname is the value type ("string", "strings", ...). pflag leaves it
+		// empty for booleans, which reads as missing data in a column headed
+		// "Type" and leaves the reader to infer that the flag takes no value, so
+		// fall back to the underlying type name. Done before the NoOptDefVal
+		// block so an optional value reads as bool[=x], matching string[="x"].
 		varname, usage := pflag.UnquoteUsage(flag)
+		if varname == "" {
+			varname = flag.Value.Type()
+		}
 		if flag.NoOptDefVal != "" {
 			switch flag.Value.Type() {
 			case "string":

internal/docgen/helpers_test.go

@@ -16,8 +16,26 @@ func TestCommandsInTable(t *testing.T) {
 	if !strings.Contains(got, "| -n, --name | string | The name |") {
 		t.Errorf("expected string type in its own column, got:\n%s", got)
 	}
-	if !strings.Contains(got, "| --verbose |  | Enable verbose |") {
-		t.Errorf("expected empty type column for bool flag, got:\n%s", got)
+	// pflag leaves the type empty for booleans; the table names it anyway so a
+	// blank cell never leaves the reader guessing what the flag takes.
+	if !strings.Contains(got, "| --verbose | bool | Enable verbose |") {
+		t.Errorf("expected bool type column for bool flag, got:\n%s", got)
+	}
+	if strings.Contains(got, "|  |") {
+		t.Errorf("expected no empty type cell, got:\n%s", got)
+	}
+}
+
+// TestCommandsInTableBoolOptionalValue checks the bool naming lands before the
+// optional-value suffix, so it reads like the string case (string[="x"]).
+func TestCommandsInTableBoolOptionalValue(t *testing.T) {
+	fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
+	fs.Bool("verbose", false, "Enable verbose")
+	fs.Lookup("verbose").NoOptDefVal = "maybe"
+
+	got := CommandsInTable(fs)
+	if !strings.Contains(got, `| --verbose | bool[=maybe] | Enable verbose |`) {
+		t.Errorf("expected bool[=maybe] in the type column, got:\n%s", got)
 	}
 }