docs/{concept,reference}: the cue vet command

This adds a brief landing page for cue-vet (at
/docs/reference/command/cue-vet/) and links to it from a new card on the
existing /docs/reference/command/ page. It adds a longer concept guide
at /docs/concept/using-the-cue-vet-command/ which describes cue-vet's
two operating modes: "CUE" mode and "data" mode.

It also includes a mention of "cue vet -c" on
/docs/concept/working-with-incomplete-cue/, so that a link to the page
from the cue-vet concept guide to explain "incompleteness" then connects
back (narratively speaking) to the concept guide. A header is added to
the existing guide in order to split it up, as it's now a little too
long just to be one section of prose.

For cue-lang/cue#2120.
Closes cue-lang/docs-and-content#192.

Preview-Path: /docs/reference/command/cue-vet/
Preview-Path: /docs/reference/command/
Preview-Path: /docs/concept/using-the-cue-vet-command/
Preview-Path: /docs/concept/using-the-cue-vet-command/validate-cue/
Preview-Path: /docs/concept/using-the-cue-vet-command/validate-data/
Preview-Path: /docs/concept/using-the-cue-vet-command/output/
Preview-Path: /docs/concept/working-with-incomplete-cue/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I4ab7af25f838b136f126e41682af9481e0eef15b
Dispatch-Trailer: {"type":"trybot","CL":1207010,"patchset":16,"ref":"refs/changes/10/1207010/16","targetBranch":"master"}

content/docs/concept/using-the-cue-vet-command/_en.md

@@ -0,0 +1,34 @@
+---
+title: Using the cue vet command
+tags: [cue command]
+authors: [jpluscplusm]
+toc_hide: true
+index_hide: true
+---
+
+The `cue vet` command is a powerful tool that checks that all your CUE code is
+consistent, and validates the contents of your data files against your
+contraints - whether they're stored as CUE, or encoded using other schema
+formats like JSON Schema or Protocol Buffers.
+
+## What's in this guide?
+
+This guide shows you how to use the `cue vet` command to check your CUE code,
+and how to validate data files against constraints encoded in any supported
+format.
+
+Here's what you'll find:
+
+{{< cards >}}
+{{< card href="validate-cue/" title="Checking CUE" label=" " >}}
+  Learn how to use `cue vet` to make sure that all your CUE code is consistent.
+{{< /card >}}
+
+{{< card href="validate-data/" title="Validating Data" label=" " >}}
+  Validate your data using CUE's succinct constraint language alongside non-CUE encodings.
+{{< /card >}}
+
+{{< card href="output/" title="Command Output" label=" " >}}
+  Change some aspects of `cue vet`'s output to suit your processes and workflows.
+{{< /card >}}
+{{< /cards >}}

content/docs/concept/using-the-cue-vet-command/output/en.md

@@ -0,0 +1,77 @@
+---
+title: Modifying command output
+---
+
+As shown throughout this guide, the `cue vet` command is either silent when
+all its inputs validate successfully, or it displays error messages identifying
+the cause of any validation failures.
+
+By default, in addition to checking that there are no data inconsistencies,
+`cue vet` verifies that its inputs are
+[*complete*]({{< relref "docs/concept/working-with-incomplete-cue" >}}).
+In other words, it ensures that
+[`cue export`]({{< relref "docs/reference/command/cue-export" >}})
+would be able to produce a JSON or YAML configuration if it were invoked.
+`cue vet` displays a general error if this is not the case:
+
+{{{with code "en" "concrete fail without -c"}}}
+#location top bottom
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+A: int & >100
+-- out --
+some instances are incomplete; use the -c flag to show errors or suppress this message
+{{{end}}}
+
+To display specific errors about incomplete regular fields use the `--concrete`/`-c` flag:
+
+{{{with code "en" "concrete fail with -c"}}}
+! exec cue vet -c
+cmp stderr out
+-- file.cue --
+package example
+
+A: int & >100
+-- out --
+A: incomplete value >100 & int
+{{{end}}}
+
+To permit incomplete fields, and to check only for consistency, use `--concrete=false`/`-c=false`:
+
+{{{with code "en" "concrete pass with -c=false"}}}
+exec cue vet -c=false
+cmp stderr out
+-- file.cue --
+package example
+
+A: int & >100
+-- out --
+{{{end}}}
+
+You can use `cue vet -c=false` to find consistency errors in your CUE:
+
+{{{with code "en" "incomplete & inconsistent fail with -c=false"}}}
+#location top bottom
+! exec cue vet -c=false
+cmp stderr out
+-- file.cue --
+package example
+
+A: int & string
+-- out --
+A: conflicting values int and string (mismatched types int and string):
+    ./file.cue:3:4
+    ./file.cue:3:10
+{{{end}}}
+
+## Related content
+
+- {{<linkto/related/reference "command/cue-vet">}}
+- {{<linkto/related/reference "command/cue-help-vet">}} -- the help text displayed by `cue help vet`
+- {{<issue"3733">}}Issue #3733{{</issue>}} tracks an effort to re-think how
+  `cue vet` operates -- if you'd like to provide feedback about ways that the
+  command could be improved to help your workflows, the CUE project would love
+  to hear it in that issue!

content/docs/concept/using-the-cue-vet-command/output/gen_cache.cue

@@ -0,0 +1,23 @@
+package site
+{
+	content: {
+		docs: {
+			concept: {
+				"using-the-cue-vet-command": {
+					output: {
+						page: {
+							cache: {
+								code: {
+									"concrete fail without -c":                     "FlcfvkgiZceBdmScYGyGu46xsBIwk9atzFQbGhpy3mo="
+									"concrete fail with -c":                        "E17TR8c0t6Lmo7y9TSisY6qfv7VW4U4hsRrNGgGn7jg="
+									"concrete pass with -c=false":                  "rHPVYjCivPeKEwPRtsb/K4qeYQAjE8NDlK4iCbOhYsg="
+									"incomplete & inconsistent fail with -c=false": "RRUxl44G9pDPGdFB0uTYYgHCDHQuLMA7CO0eBCawTMA="
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/concept/using-the-cue-vet-command/output/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: concept: "using-the-cue-vet-command": output: page: _

content/docs/concept/using-the-cue-vet-command/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: concept: "using-the-cue-vet-command": page: _

content/docs/concept/using-the-cue-vet-command/validate-cue/en.md

@@ -0,0 +1,205 @@
+---
+title: Validating CUE
+weight: 10
+tags: [cue command]
+authors: [jpluscplusm]
+toc_hide: false
+---
+
+The `cue vet` command takes any number of inputs, and checks that their
+contents are acceptable -- it *validates* the inputs. The command runs in one
+of its two validation modes: "CUE" or "data". This page describes "CUE" mode,
+which is the command's default. "Data" mode (and how to activate it) is
+detailed on the [next page of this guide]({{<relref"validate-data">}}).
+
+## CUE inputs
+
+If `cue vet` is called without any input arguments then it validates the single
+CUE package in the current directory:
+
+{{{with code "en" "0 args pass"}}}
+exec cue vet
+cmp stderr out
+-- file.cue --
+package alpha
+
+A: 99 & int
+-- out --
+{{{end}}}
+
+The command succeeds silently if the input validates successfully.
+Otherwise, the command fails and displays an error message for each validation failure:
+
+{{{with code "en" "0 args fail"}}}
+#location top bottom
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package alpha
+
+A: 99 & >100
+B: 99 & string
+-- out --
+B: conflicting values 99 and string (mismatched types int and string):
+    ./file.cue:4:4
+    ./file.cue:4:9
+A: invalid value 99 (out of bound >100):
+    ./file.cue:3:9
+    ./file.cue:3:4
+{{{end}}}
+
+Another way to refer to the single package in the current directory is with the
+shorthand of "`.`".
+
+If there's more than one package in the current directory then you need to tell
+`cue vet` which package it should validate ... or else the command fails:
+
+{{{with code "en" "0 args fail >1 packages"}}}
+#location top-left top-right bottom
+! exec cue vet .
+cmp stderr out
+-- a.cue --
+package alpha
+
+A: 1
+-- b.cue --
+package beta
+
+A: 1
+-- out --
+found packages "alpha" (a.cue) and "beta" (b.cue) in "."
+{{{end}}}
+
+Read on for information about how to specify which CUE packages and files `cue
+vet` should validate.
+
+### CUE package inputs
+
+The `cue vet` command can validate any number of CUE packages, which are
+identified by their *import path*.
+Both *relative* and *absolute* import paths can be specified -- see
+`{{<linkto/inline "reference/command/cue-help-inputs">}}` for more information
+about their differences. We'll use paths that start with `.` in our examples,
+which are relative import paths that are interpreted as filesystem paths.
+
+To validate a specific package in a relative import path's directory, even when
+there's more than one package present, use a `:<package-name>` suffix to
+specify the package:
+
+{{{with code "en" "1 arg pass"}}}
+#location top-left top-right bottom
+exec cue vet ./dir:beta # only package "beta" is checked, so this succeeds
+cmp stderr out
+-- dir/a.cue --
+package alpha
+
+A: false & true // This is invalid.
+-- dir/b.cue --
+package beta
+
+A: 42
+-- out --
+{{{end}}}
+
+If you need to validate more than one package then specify multiple import
+paths as input parameters. Each package is validated *seperately*, in isolation
+from any other packages. If you hand `cue vet` more than one package as its
+inputs, then you must *only* specify CUE packages to validate. You can't mix
+multiple CUE packages with any other input types.
+
+### CUE file inputs
+
+By telling `cue vet` about one or more CUE files you can check that they're all
+valid, and can unify successfully:
+
+{{{with code "en" "fail file + file"}}}
+#location top-left top-right bottom
+! exec cue vet a1.cue a2.cue
+cmp stderr out
+-- a1.cue --
+package alpha
+
+A: int
+B: int & >100
+-- a2.cue --
+package alpha
+
+A: 42
+B: 42
+-- out --
+B: invalid value 42 (out of bound >100):
+    ./a1.cue:4:10
+    ./a2.cue:4:4
+{{{end}}}
+
+When you provide more than one CUE files as inputs to `cue vet`,
+each CUE file you mention must either:
+
+- belong to the same package as all the other CUE files that have a `package`
+  clause, or
+- not have a `package` clause.
+
+You can also check that an arbitrary number of CUE files unify successfully
+with a single CUE package.
+Make sure to specify the package as the first input:
+
+{{{with code "en" "fail package + package-file + file"}}}
+#location top-left top-right top-right bottom
+! exec cue vet .:alpha b.cue x.cue
+cmp stderr out
+-- a.cue --
+package alpha
+
+A: int
+B: float
+-- b.cue --
+package beta
+
+A: 4.2
+-- x.cue --
+B: 42
+-- out --
+A: conflicting values 4.2 and int (mismatched types float and int):
+    ./a.cue:3:4
+    ./b.cue:3:4
+B: conflicting values 42 and float (mismatched types int and float):
+    ./a.cue:4:4
+    ./x.cue:1:4
+{{{end}}}
+
+As before, all the individually-mentioned CUE files are unified with each
+other, so they must either have the same `package` clause or no
+`package` clause at all. However, their `package` clause does *not* have to
+match the name of the package against which they're being checked.
+
+The standard input stream of the `cue vet` command can be included as an input
+and unified with the other inputs via its special symbol "`-`", as outlined in
+`{{< linkto/inline "reference/command/cue-help-inputs" >}}`.
+It's treated as if it were any other CUE file mentioned as an input -- so it
+also needs to have a `package` clause that matches the other CUE files, or no
+`package` clause at all.
+
+## Using CUE to validate your data
+
+The [next page of this guide]({{<relref"validate-data">}}) explains using `cue
+vet` to validate data encoded as JSON, YAML, and other formats.
+
+## Validation output
+
+The `cue vet` command succeeds silently when data validation succeeds, which
+means that the command produces no output and its exit code is 0.
+
+If there's a problem with your CUE then `cue vet` displays error messages, as
+described above. The
+[final page of this guide]({{<relref"output">}}) shows you how to change the
+command's output, and how it checks for *incomplete* values.
+
+## Related content
+
+- {{<linkto/related/reference"command/cue-help-inputs">}} -- help text explaining how CUE's inputs can be specified
+- {{<linkto/related/reference"command/cue-vet">}}
+- {{<linkto/related/reference "command/cue-help-vet">}} -- the help text displayed by `cue help vet`
+- {{<issue"3733">}}Issue #3733{{</issue>}} tracks an effort to re-think how
+  `cue vet` operates -- if you'd like to provide feedback about ways that the
+  command could be improved to help your workflows, the CUE project would love
+  to hear it in that issue!

content/docs/concept/using-the-cue-vet-command/validate-cue/gen_cache.cue

@@ -0,0 +1,25 @@
+package site
+{
+	content: {
+		docs: {
+			concept: {
+				"using-the-cue-vet-command": {
+					"validate-cue": {
+						page: {
+							cache: {
+								code: {
+									"0 args pass":                        "SHVISiwanUJjeHheHaSKPq72pLjTCKeGd3e7bLfVhjk="
+									"0 args fail":                        "CfvKW1fm45dNlywYvzvwhxzQId6pA629aPwQ4JcKhy0="
+									"0 args fail >1 packages":            "dnpQ5eK80/00R7bUThscdL424p2gilMAnLBz/rmaTrE="
+									"1 arg pass":                         "0g/8bsOhQe26oxPIXxgtwFWkkW6++yEsgpfeRJJnx5s="
+									"fail file + file":                   "Ua2h5Ma728IL71NvUbPk1YYhR6r16CTWYwp2YNOw1Eo="
+									"fail package + package-file + file": "KfXunyoQaORqvKkx+S2MoUeXv4MMCpdN+N8CIIrCX8o="
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/concept/using-the-cue-vet-command/validate-cue/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: concept: "using-the-cue-vet-command": "validate-cue": page: _