tofu show: new explicit/extensible usage style

The "tofu show" command has historically been difficult to extend to meet
new use-cases, such as showing the current configuration without creating
a plan, because it was designed to take zero or one arguments and then try
to guess what the one specified argument was intended to mean.

This commit introduces a new style where the type of object to inspect is
specified using command line option syntax, using one of two
mutually-exclusive options:

    -state      Show the latest state snapshot.
    -plan=FILE  Show the plan from the given saved plan file.

We expect that a future commit will extend this with a new "-config" option
to inspect the configuration rooted in the current working directory, and
possibly with "-module=DIR" to shallowly inspect a single module without
necessarily having to fully initialize it with all of its dependencies
first. However, both of those use-cases (and any others) are not in scope
for this commit, which is focused only on refactoring to make those future
use-cases possible.

The old mode of specifying neither option and providing zero or one
positional arguments is still supported for backward compatibility.
Notably, the legacy style is the only way to access the legacy behavior of
inspecting a specific state snapshot file from the local filesystem, which
has not often been used since Terraform v0.9 as we've moved away
from manual management of state files to the structure of state backends.
Those who _do_ still need that old behavior can still access it in the
old way, but there will be no new-style equivalent of it unless we learn
of a compelling use case for it.

Signed-off-by: Martin Atkins <mart@degeneration.co.uk>

website/docs/cli/commands/show.mdx

@@ -1,53 +1,88 @@
 ---
 description: >-
-  The `tofu show` command is used to provide human-readable output from a
-  state or plan file. This can be used to inspect a plan to ensure that the
-  planned operations are expected, or to inspect the current state as OpenTofu
-  sees it.
+  The tofu show command can inspect various OpenTofu artifacts and produce
+  either human-readable or machine-readable descriptions.
 ---
 
 # Command: show
 
-The `tofu show` command is used to provide human-readable output
-from a state or plan file. This can be used to inspect a plan to ensure
-that the planned operations are expected, or to inspect the current state
-as OpenTofu sees it.
+The `tofu show` command can inspect various OpenTofu artifacts and produce
+either human-readable or machine-readable descriptions.
 
-Machine-readable output is generated by adding the `-json` command-line
-flag.
+For example, you can use `tofu show` to inspect a saved plan file to check
+that the planned operations are acceptable, or to inspect the latest state
+snapshot.
 
 :::note
 When using the `-json` command-line flag, any sensitive values in
-OpenTofu state will be displayed in plain text. For more information, see
+OpenTofu state will be returned in plain text. For more information, see
 [Sensitive Data in State](../../language/state/sensitive-data.mdx).
 :::
 
-## JSON Output
-
-For OpenTofu state files (including when no path is provided),
-`tofu show -json` will show a JSON representation of the state.
-
-For OpenTofu plan files, `tofu show -json` will show a JSON representation
-of the plan, configuration, and current state.
-
-If you've updated providers which contain new schema versions since the state
-was written, the state needs to be upgraded before it can be displayed with
-`show -json`. If you are viewing a plan, it must be created without
-`-refresh=false`. If you are viewing a state file, run `tofu refresh`
-first.
-
-The output format is covered in detail in [JSON Output Format](../../internals/json-format.mdx).
-
 ## Usage
 
-Usage: `tofu show [options] [file]`
+Usage: `tofu show [target-selection-option] [other-options]`
 
-You may use `show` with a path to either a OpenTofu state file or plan
-file. If you don't specify a file path, OpenTofu will show the latest state
-snapshot.
+Use one of the following target selection options to specify the artifact
+to inspect:
 
-This command accepts the following options:
+- `-state`: Inspect the latest state snapshot, if any.
+- `-plan=FILENAME`: Inspect the plan stored in the given saved plan file.
 
-* `-no-color` - Disables output with coloring
+The `-state` option is the default if none of these options are used. The
+target-selection options are mutually-exclusive.
 
-* `-json` - Displays machine-readable output from a state or plan file
+This command also accepts the following additional options:
+
+- `-no-color`: Disables the use of terminal escape sequences in
+  human-oriented output.
+- `-json`: Selects the machine-readable JSON output format, instead
+  of the default human-oriented output.
+- `-var` and `-var-file`: Specifies values for any input variables
+  used in module source addresses or backend settings in the
+  current configuration.
+
+This command relies on schema information from provider plugins to fully
+understand the provider-specific data structures in state, plan, and
+configuration artifacts. If you are currently using different provider
+versions than were used when creating the selected artifact then
+you may need to use `tofu apply` (or similar) to allow OpenTofu to
+upgrade the stored data to match the latest provider schemas.
+
+## JSON Output
+
+When using the `-json` option, the structure of the machine-readable output
+depends on the selected artifact type:
+
+- `-state` returns [the JSON state representation](../../internals/json-format.mdx#state-representation).
+- `-plan=FILENAME` returns the [the JSON plan representation](../../internals/json-format.mdx#plan-representation),
+  which also includes information about the configuration and
+  prior state that the plan was based on.
+
+## Legacy Usage
+
+For backward compatibility with older versions of OpenTofu, this
+command also supports a different usage pattern:
+
+`tofu show [other-options] <filename>`
+
+In this style, none of the explicit target selection options can be used
+and instead OpenTofu inspects the given file and reacts in the following
+ways:
+
+- If the file can be loaded as a saved plan file, behaves like `-plan=FILENAME`
+  with the same file.
+- If the file can be parsed as a local state snapshot file such as those
+  created by `tofu state pull`, inspects the content of that state file
+  using the same output format as would normally be used to inspect the
+  latest state snapshot.
+
+    The selected state snapshot file must be one associated with the
+    configuration in the current working directory, or else the results
+    are unspecified because the available providers might not match
+    those that were used to create the data in the state snapshot.
+
+Unless you need the legacy behavior of inspecting an arbitrary state
+snapshot file, we recommend using the new explicit target selection
+options to make it clearer to OpenTofu what artifact type you wish to
+inspect.