Add Explain command

Author: joe-chacko

src/main/java/io/openliberty/explore/DescribeCommand.java

@@ -0,0 +1,82 @@
+/*
+ * =============================================================================
+ * Copyright (c) 2022,2024 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v2.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v20.html
+ *
+ * Contributors:
+ *     IBM Corporation - initial API and implementation
+ * =============================================================================
+ */
+package io.openliberty.explore;
+
+import java.util.EnumMap;
+import java.util.List;
+import static java.util.function.Predicate.not;
+import java.util.stream.Collectors;
+
+import io.openliberty.inspect.Visibility;
+import io.openliberty.inspect.feature.Feature;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Parameters;
+import picocli.CommandLine.ParentCommand;
+
+@Command(
+        name = "explain",
+        description = "Produce a detailed description of the specified elements"
+)
+public class ExplainCommand {
+    private static final String BULLET_POINT = "  - ";
+    
+    @ParentCommand
+    private LibertyExplorer explorer;
+
+    @Command(name = "features", description = "Explain a feature")
+    void features(
+            @Parameters(arity = "1..*", description = "one or more glob patterns to match features by name", defaultValue = "*")
+            List<String> patterns
+            ) throws Exception {
+        explorer.init(patterns); // find all features
+        explorer.allResults()
+                .stream()
+                .filter(Feature.class::isInstance)
+                .map(Feature.class::cast)
+                .sorted()
+                .forEach(this::explain);
+    }
+
+    private static EnumMap<Visibility, String> VIS_DESCS = new EnumMap<>(Visibility.class);
+
+    private void explain(Feature f) {
+        // Heading
+        String name = f.name();
+        System.out.println(name);
+        System.out.println(name.replaceAll(".", "="));
+        // Feature names
+        System.out.printf("The feature %s is defined by the file: %s%n", f.symbolicName(), f.path());
+        f.shortName().ifPresent(n -> System.out.printf("It is also known by its short name: %s%n", n));
+        // Describe visibility, auto-ness, and include embedded description
+        System.out.printf(switch (f.visibility()) {
+            case PUBLIC -> "This is a public feature; it can be configured directly in server configuration,"
+                    + " or included by Liberty or extension features.%n"
+                    + f.description() + "%n";
+            case PROTECTED -> "This is a protected feature; it can be included by Liberty or extension features.%n";
+            case PRIVATE -> f.isAutoFeature() ?
+                    "This is an auto-feature; it will be included automatically based on the presence of other features in combination.%n" :
+                    "This is a private feature; it can be included by other Liberty features.%n";
+            default -> "The visibility of this feature is unknown.%n";
+        });
+        boolean hasFeatureDeps = f.hasFeatureDependencies();
+        if (hasFeatureDeps) {
+            System.out.println("This feature includes the following features:");
+            f.formatFeatureDependencies().map(BULLET_POINT::concat).forEach(System.out::println);
+        }
+        if (f.hasBundleDependencies()) {
+            System.out.println(hasFeatureDeps ? "and the following bundles:" : "This feature includes the following bundles:");
+            f.formatBundleDependencies().map(BULLET_POINT::concat).forEach(System.out::println);
+        }
+        System.out.println();
+    }
+}

src/main/java/io/openliberty/explore/ExplainCommand.java

@@ -13,43 +13,49 @@
 package io.openliberty.explore;
 
 
-import io.openliberty.inspect.Catalog;
-import io.openliberty.inspect.Element;
+import java.nio.file.Path;
+import java.util.Arrays;
+import static java.util.Collections.emptySet;
+import static java.util.Collections.unmodifiableSet;
+import java.util.HashSet;
+import java.util.List;
+import static java.util.Objects.requireNonNull;
+import java.util.Set;
+import static java.util.function.Predicate.not;
+import java.util.stream.Collectors;
+import static java.util.stream.Collectors.toUnmodifiableList;
+import static java.util.stream.Collectors.toUnmodifiableSet;
+import java.util.stream.Stream;
+
 import org.jgrapht.Graph;
 import org.jgrapht.GraphPath;
 import org.jgrapht.alg.shortestpath.AllDirectedPaths;
 import org.jgrapht.graph.AsGraphUnion;
 import org.jgrapht.graph.AsSubgraph;
 import org.jgrapht.graph.DefaultEdge;
 import org.jgrapht.graph.EdgeReversedGraph;
+
+import static io.openliberty.GraphCollectors.toUnionWith;
+import static io.openliberty.explore.LibertyExplorer.Direction.FORWARD;
+import static io.openliberty.explore.LibertyExplorer.Direction.REVERSE;
+import io.openliberty.inspect.Catalog;
+import io.openliberty.inspect.Element;
 import picocli.CommandLine;
 import picocli.CommandLine.Command;
 import picocli.CommandLine.HelpCommand;
 import picocli.CommandLine.Option;
 import picocli.CommandLine.PropertiesDefaultProvider;
 
-import java.nio.file.Path;
-import java.util.HashSet;
-import java.util.List;
-import java.util.Set;
-import java.util.stream.Collectors;
-import java.util.stream.Stream;
-
-import static io.openliberty.GraphCollectors.toUnionWith;
-import static io.openliberty.explore.LibertyExplorer.Direction.FORWARD;
-import static io.openliberty.explore.LibertyExplorer.Direction.REVERSE;
-import static java.util.Collections.emptySet;
-import static java.util.Collections.unmodifiableSet;
-import static java.util.Objects.requireNonNull;
-import static java.util.function.Predicate.not;
-import static java.util.stream.Collectors.toUnmodifiableList;
-import static java.util.stream.Collectors.toUnmodifiableSet;
-
 @Command(
         name = "lx",
         description = "Liberty installation eXplorer",
         version = "Liberty installation eXplorer 0.5",
-        subcommands = {DescribeCommand.class, ListCommand.class, GraphCommand.class, TreeCommand.class, HelpCommand.class},
+        subcommands = {
+                ExplainCommand.class,
+                ListCommand.class,
+                GraphCommand.class,
+                TreeCommand.class,
+                HelpCommand.class},
         defaultValueProvider = PropertiesDefaultProvider.class
 )
 public class LibertyExplorer {
@@ -92,6 +98,10 @@ void init(List<String> patterns) throws Exception {
         removeExcludedElements();
     }
 
+    void init(String...patterns) throws Exception {
+        init(Arrays.asList(patterns));
+    }
+
     void removeExcludedElements() {
         // remove excluded features (and associated edges) from graph
         if (verbose) System.err.println("Exclude patterns:");

src/main/java/io/openliberty/explore/LibertyExplorer.java

@@ -61,8 +61,9 @@ public static SimpleDirectedGraph<Element, DefaultEdge> newGraph() {
     public Catalog(Path libertyRoot, boolean includeBundles) throws IOException {
         validate(libertyRoot, "Not a valid directory: ");
         Path libDir = validate(libertyRoot.resolve("lib"), "No lib subdirectory found: ");
+        Path devDir = validate(libertyRoot.resolve("dev"), "No dev subdirectory found: ");
         // parse bundles
-        if (includeBundles) Files.list(libDir)
+        if (includeBundles) Stream.concat(Files.walk(devDir),Files.list(libDir))
                 .filter(Files::isRegularFile)
                 .filter(p -> p.toString().endsWith(".jar"))
                 .map(Bundle::new)

src/main/java/io/openliberty/inspect/Catalog.java

@@ -17,12 +17,13 @@
 import org.osgi.framework.VersionRange;
 
 public class BundleSpec implements ContentSpec {
+    private final static VersionRange DEFAULT_RANGE = VersionRange.valueOf("0.0");
     final String symbolicName;
     final VersionRange versionRange;
 
     BundleSpec(ManifestValueEntry ve) {
         this.symbolicName = ve.id;
-        this.versionRange = VersionRange.valueOf(ve.getQualifierOrDefault("version", "0.0"));
+        this.versionRange = ve.getQualifierIfPresent("version").map(VersionRange::valueOf).orElse(DEFAULT_RANGE);
     }
 
     @Override
@@ -40,4 +41,14 @@ public int compareMatches(Element f1, Element f2) {
     public String toString() {
         return symbolicName + ":" + versionRange;
     }
+
+    String describe() {
+        if (DEFAULT_RANGE == versionRange) return symbolicName + " at any version."; 
+        if (versionRange.isExact()) return symbolicName + " version " + versionRange.getLeft();
+        return symbolicName + " from version " + versionRange.getLeft()
+                + (versionRange.getRightType() == VersionRange.RIGHT_CLOSED ?
+                        " up to and including ":
+                        " up to but not including ")
+                + versionRange.getRight() + versionRange.getRightType();
+    }
 }