Add optional_distros support

This provides a way to suggest blessed `--requirement`'s. This includes
a description and default value.

README.md

@@ -832,6 +832,11 @@ This config would have the URI `project_a/Thug/Animation`.
 
 Configs support [min_verbosity](#min_verbosity) [with inheritance](tests/configs/verbosity).
 
+When doing bulk editing of multiple configs, the `hab dump --type all-uris` command
+provides you with a easily diff-able json dump of the [freeze](#restoring-resolved-configuration)
+for all non-placeholder URI's defined. If a URI errors out when resolving, the
+error text is stored instead of the freeze.
+
 #### Config Inheritance
 
 When resolving a URI it will find the closest exact match, so if `project_a/Thug` is

hab/cli.py

@@ -570,7 +570,7 @@ def env(settings, uri, launch):
     "--type",
     "report_type",
     type=click.Choice(
-        ["nice", "site", "s", "uris", "u", "versions", "v", "forest", "f"]
+        ["nice", "site", "s", "uris", "u", "versions", "v", "forest", "f", "all-uris"]
     ),
     default="nice",
     help="Type of report.",
@@ -635,6 +635,12 @@ def echo_line(line):
                 truncate=truncate,
             ):
                 echo_line(line)
+    elif report_type == "all-uris":
+        # Combines all non-placeholder URI's into a single json document and display.
+        # This can be used to compare changes to configs when editing them in bulk.
+        ret = resolver.freeze_configs()
+        ret = utils.dumps_json(ret, indent=2)
+        click.echo(ret)
     elif report_type == "site":
         click.echo(resolver.site.dump(verbosity=verbosity))
     else:

hab/resolver.py

@@ -264,6 +264,26 @@ def find_distro(self, requirement):
             app = self.distros[requirement.name]
             return app.latest_version(requirement)
 
+    def freeze_configs(self):
+        """Returns a composite dict of the freeze for all URI configs.
+
+        Returns a dict for every non-placeholder URI where the value is the freeze
+        dict of that URI. If a error is encountered when generating the freeze
+        the exception subject is stored as a string instead.
+        """
+        out = {}
+        for node in self.dump_forest(self.configs, attr=None):
+            if isinstance(node.node, HabBase._placeholder):
+                continue
+            uri = node.node.uri
+            try:
+                cfg = self.resolve(uri)
+            except Exception as error:
+                out[uri] = f"Error resolving {uri}: {error}"
+            else:
+                out[uri] = cfg.freeze()
+        return out
+
     @classmethod
     def instance(cls, name="main", **kwargs):
         """Returns a shared Resolver instance for name, initializing it if required.

tests/conftest.py

@@ -175,6 +175,33 @@ def reset_environ():
             os.environ.clear()
             os.environ.update(old_environ)
 
+    @staticmethod
+    def compare_files(generated, check):
+        """Assert two files are the same with easy to read errors.
+
+        First compares the number of lines for differences, then checks each line
+        for differences raising an AssertionError on the first difference.
+
+        Args:
+            generated (pathlib.Path): The file generated for testing. This will
+                have a newline added to the end to match the pre-commit enforced
+                "fix end of files" check.
+            check (pathlib.Path): Compare generated to this check file. It is
+                normally committed inside the hab/tests folder.
+        """
+        check = check.open().readlines()
+        cache = generated.open().readlines()
+        # Add trailing white space to match template file's trailing white space
+        cache[-1] += "\n"
+        assert len(cache) == len(
+            check
+        ), f"Generated cache does not have the same number of lines: {check}"
+
+        for i in range(len(cache)):
+            assert (
+                cache[i] == check[i]
+            ), f"Difference on line: {i} between the generated cache and {generated}."
+
 
 @pytest.fixture
 def helpers():