Add DependencyTracker for symbols

This tracker can be used to manage and query dependencies, to track
dependencies that need to be used at runtime by generated code, and load
dependencies from a JSON file.

Author: mtdowling

smithy-codegen-core/src/main/java/software/amazon/smithy/codegen/core/DependencyTracker.java

@@ -0,0 +1,281 @@
+/*
+ * Copyright 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.smithy.codegen.core;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.UncheckedIOException;
+import java.net.URL;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.node.NodeMapper;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.utils.SetUtils;
+
+/**
+ * A container for all known dependencies of a generator.
+ *
+ * <p>A DependencyTracker can include predefined dependencies loaded from a
+ * file (for example to track versions of runtime dependencies used in the
+ * generator), or dependencies that are accumulated dynamically as code is
+ * generated.
+ *
+ * <p>Notes:
+ * <ul>
+ *     <li>Multiple packages of the same name and type can be added to tracker.
+ *     There's no de-duplication.</li>
+ *     <li>Note that this class is mutable and not synchronized.</li>
+ * </ul>
+ *
+ * <h2>Loading from JSON</h2>
+ *
+ * <p>Dependencies can be loaded from a JSON file to more easily track
+ * dependencies used at runtime by generated code. This feature can also
+ * be used to generate the dependencies tracked by the generated from from
+ * other dependency graph formats like lockfiles.
+ *
+ * <p>The JSON file has the following format:
+ *
+ * <pre>
+ * {@code
+ * {
+ *     "version": "1.0",
+ *     "dependencies": [
+ *         {
+ *             "packageName": "string",
+ *             "version": "string",
+ *             "dependencyType": "string",
+ *             "properties": {
+ *                 "x": true,
+ *                 "y": [10],
+ *                 "z": "string"
+ *             }
+ *         }
+ *     ]
+ * }
+ * }
+ * </pre>
+ *
+ * <ul>
+ *     <li>"version" (string, required): Must be set to "1.0".</li>
+ *     <li>"dependencies" is a list of dependency objects that contain the following
+ *         properties:
+ *         <ul>
+ *             <li>"packageName" (string, required): The required name of the package.</li>
+ *             <li>"version" (string, required): The required dependency version.</li>
+ *             <li>"dependencyType" (string): The optional type of dependency. This value
+ *             is dependent on the package manager of the target environment.</li>
+ *             <li>"properties" (map of string to any value): Properties to assign to
+ *             the symbol. These properties can be any JSON value type other than null.
+ *             List values are converted to a {@link List}, map values are converted to
+ *             a {@link Map}, boolean values to Java's boolean, numeric values to an
+ *             appropriate {@link Number} type, and string values to {@link String}.</li>
+ *         </ul>
+ *     </li>
+ * </ul>
+ */
+public final class DependencyTracker implements SymbolDependencyContainer {
+
+    private static final String VERSION = "version";
+    private static final String DEPENDENCIES = "dependencies";
+    private static final String PACKAGE_NAME = "packageName";
+    private static final String DEPENDENCY_TYPE = "dependencyType";
+    private static final String PROPERTIES = "properties";
+    private static final Set<String> TOP_LEVEL_PROPERTIES = SetUtils.of(VERSION, DEPENDENCIES);
+    private static final Set<String> ALLOWED_SYMBOL_PROPERTIES = SetUtils.of(
+            PACKAGE_NAME, DEPENDENCY_TYPE, VERSION, PROPERTIES);
+
+    private final List<SymbolDependency> dependencies = new ArrayList<>();
+
+    @Override
+    public List<SymbolDependency> getDependencies() {
+        return dependencies;
+    }
+
+    /**
+     * Gets the first found dependency by name.
+     *
+     * @param name Package name of the dependency to get.
+     * @return Returns the dependency.
+     * @throws IllegalArgumentException if the dependency cannot be found.
+     */
+    public SymbolDependency getByName(String name) {
+        for (SymbolDependency dependency : dependencies) {
+            if (dependency.getPackageName().equals(name)) {
+                return dependency;
+            }
+        }
+        throw new IllegalArgumentException("Unknown dependency '" + name + "'. Known dependencies: " + dependencies);
+    }
+
+    /**
+     * Gets the first found dependency by name and dependency type.
+     *
+     * @param name Package name of the dependency to get.
+     * @param dependencyType The dependency type of package to find.
+     * @return Returns the dependency.
+     * @throws IllegalArgumentException if the dependency cannot be found.
+     */
+    public SymbolDependency getByName(String name, String dependencyType) {
+        for (SymbolDependency dependency : dependencies) {
+            if (dependency.getPackageName().equals(name) && dependency.getDependencyType().equals(dependencyType)) {
+                return dependency;
+            }
+        }
+        throw new IllegalArgumentException("Unknown dependency '" + name + "' of type '" + dependencyType + "'. "
+                                           + "Known dependencies: " + dependencies);
+    }
+
+    /**
+     * Gets a list of matching dependencies that have a dependency type
+     * matching {@code dependencyType}.
+     *
+     * @param dependencyType Dependency type to find.
+     * @return Returns the matching dependencies.
+     */
+    public List<SymbolDependency> getByType(String dependencyType) {
+        List<SymbolDependency> result = new ArrayList<>();
+        for (SymbolDependency dependency : dependencies) {
+            if (dependency.getDependencyType().equals(dependencyType)) {
+                result.add(dependency);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Gets a list of matching dependencies that contain a property named
+     * {@code property}.
+     *
+     * @param property Property to find.
+     * @return Returns the matching dependencies.
+     */
+    public List<SymbolDependency> getByProperty(String property) {
+        List<SymbolDependency> result = new ArrayList<>();
+        for (SymbolDependency dependency : dependencies) {
+            if (dependency.getProperty(property).isPresent()) {
+                result.add(dependency);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Gets a list of matching dependencies that contain a property named
+     * {@code property} with a value of {@code value}.
+     *
+     * @param property Property to find.
+     * @param value Value to match.
+     * @return Returns the matching dependencies.
+     */
+    public List<SymbolDependency> getByProperty(String property, Object value) {
+        List<SymbolDependency> result = new ArrayList<>();
+        for (SymbolDependency dependency : dependencies) {
+            if (dependency.getProperty(property).filter(p -> p.equals(value)).isPresent()) {
+                result.add(dependency);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Adds a dependency.
+     *
+     * @param dependency Dependency to add.
+     */
+    public void addDependency(SymbolDependency dependency) {
+        dependencies.add(dependency);
+    }
+
+    /**
+     * Adds a dependency.
+     *
+     * @param packageName Name of the dependency.
+     * @param version Version of the dependency.
+     * @param dependencyType Type of dependency (e.g., "dev", "test", "runtime", etc).
+     *                       This value wholly depends on the type of dependency graph
+     *                       being generated.
+     */
+    public void addDependency(String packageName, String version, String dependencyType) {
+        SymbolDependency dependency = SymbolDependency.builder()
+                .packageName(packageName)
+                .version(version)
+                .dependencyType(dependencyType)
+                .build();
+        addDependency(dependency);
+    }
+
+    /**
+     * Adds dependencies from a {@link SymbolDependencyContainer}.
+     *
+     * @param container Container to copy depdencies from.
+     */
+    public void addDependencies(SymbolDependencyContainer container) {
+        for (SymbolDependency dependency : container.getDependencies()) {
+            addDependency(dependency);
+        }
+    }
+
+    /**
+     * Loads predefined dependencies from a JSON file (for example, to track
+     * known dependencies used by generated code at runtime).
+     *
+     * <pre>
+     * {@code
+     * DependencyTracker tracker = new DependencyTracker();
+     * tracker.addDependenciesFromJson(getClass().getResource("some-file.json"));
+     * }
+     * </pre>
+     *
+     * @param jsonFile URL location of the JSON file.
+     */
+    public void addDependenciesFromJson(URL jsonFile) {
+        Objects.requireNonNull(jsonFile, "Dependency JSON file is null, probably because the file could not be found.");
+        try (InputStream stream = jsonFile.openConnection().getInputStream()) {
+            parseDependenciesFromJson(Node.parse(stream));
+        } catch (IOException e) {
+            throw new UncheckedIOException("Error loading dependencies from "
+                                           + jsonFile + ": " + e.getMessage(), e);
+        }
+    }
+
+    private void parseDependenciesFromJson(Node node) {
+        NodeMapper mapper = new NodeMapper();
+        ObjectNode root = node.expectObjectNode();
+        root.warnIfAdditionalProperties(TOP_LEVEL_PROPERTIES);
+        // Must define a version.
+        root.expectStringMember(VERSION).expectOneOf("1.0");
+        // Must define a list of dependencies, each an ObjectNode.
+        for (ObjectNode value : root.expectArrayMember(DEPENDENCIES).getElementsAs(ObjectNode.class)) {
+            value.warnIfAdditionalProperties(ALLOWED_SYMBOL_PROPERTIES);
+            SymbolDependency.Builder builder = SymbolDependency.builder();
+            builder.packageName(value.expectStringMember(PACKAGE_NAME).getValue());
+            builder.version(value.expectStringMember(VERSION).getValue());
+            value.getStringMember(DEPENDENCY_TYPE).ifPresent(v -> builder.dependencyType(v.getValue()));
+            value.getObjectMember(PROPERTIES).ifPresent(properties -> {
+                for (Map.Entry<String, Node> entry : properties.getStringMap().entrySet()) {
+                    Object nodeAsJavaValue = mapper.deserialize(entry.getValue(), Object.class);
+                    builder.putProperty(entry.getKey(), nodeAsJavaValue);
+                }
+            });
+            addDependency(builder.build());
+        }
+    }
+}