/*
    * Licensed to the Apache Software Foundation (ASF) under one
    * or more contributor license agreements.  See the NOTICE file
    * distributed with this work for additional information
    * regarding copyright ownership.  The ASF licenses this file
    * to you under the Apache License, Version 2.0 (the
    * "License"); you may not use this file except in compliance
    * with the License.  You may obtain a copy of the License at
    *
   *   http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing,
   * software distributed under the License 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 org.eclipse.aether.tools;
  
  import javax.tools.DiagnosticCollector;
  import javax.tools.DocumentationTool;
  import javax.tools.JavaFileObject;
  import javax.tools.StandardJavaFileManager;
  import javax.tools.StandardLocation;
  import javax.tools.ToolProvider;
  
  import java.io.File;
  import java.io.IOException;
  import java.io.PrintWriter;
  import java.io.Reader;
  import java.io.Writer;
  import java.net.URI;
  import java.net.URISyntaxException;
  import java.net.URL;
  import java.net.URLClassLoader;
  import java.nio.charset.StandardCharsets;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Comparator;
  import java.util.LinkedHashMap;
  import java.util.List;
  import java.util.Map;
  import java.util.Objects;
  import java.util.Properties;
  import java.util.concurrent.Callable;
  import java.util.stream.Collectors;
  import java.util.stream.Stream;
  
  import org.apache.velocity.VelocityContext;
  import org.apache.velocity.app.VelocityEngine;
  import org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader;
  import org.codehaus.plexus.util.io.CachingWriter;
  import picocli.CommandLine;
  
  /**
   * This tool is used both from <a href="https://github.com/apache/maven-resolver/blob/79d102b66235f33ad1e6134e18451ac3ee91b44a/maven-resolver-tools/pom.xml#L185">Resolver</a>
   * as well as from <a href="https://github.com/apache/maven/blob/7aa3c8a37b091a5a86d3dae3a7d99ce910fd6caa/pom.xml#L1043">Maven</a>
   * to generate documentation for configuration keys. It scans the source files under a given root directory, collects the configuration keys declared in them and renders them into Velocity templates.
   * It relies on javadoc with a custom doclet to extract the configuration keys from the source files.
   * The doclet writes the discovered keys into an intermediate properties file, which is then read back and used to render the Velocity templates.
   */
  @CommandLine.Command(name = "docgen", description = "Configuration Documentation Generator")
  public class CollectConfiguration implements Callable<Integer> {
      public static void main(String[] args) {
          new CommandLine(new CollectConfiguration()).execute(args);
      }
  
      protected static final String KEY = "key";
  
      /**
       * The metadata fields collected per configuration key and written to / read from the intermediate properties file.
       */
      protected static final List<String> FIELDS = List.of(
              KEY,
              "defaultValue",
              "fqName",
              "description",
              "since",
              "configurationSource",
              "configurationType",
              "configurationTypeJavadocUrl",
              "supportRepoIdSuffix",
              "deprecated",
              "see");
  
      /**
       * Javadoc block tag marking a constant field as a configuration key.
       */
      protected static final String CONFIGURATION_MARKER = "@configurationSource";
  
      /**
       * Text marker used to pre-select the source files to feed the doclet when scanning Maven sources. Maven declares
       * configuration keys via the {@code org.apache.maven.api.annotations.Config} annotation.
       */
      protected static final String MAVEN_CONFIGURATION_MARKER = "@Config";
  
     /**
      * The mode of the generator, i.e. what kind of sources are being scanned.
      */
     public enum Mode {
         maven,
         resolver
     }
 
     @CommandLine.Option(
             names = {"-m", "--mode"},
             arity = "1",
             paramLabel = "mode",
             description = "The mode of generator (what is being scanned?), supported modes are 'maven', 'resolver'")
     protected Mode mode = Mode.resolver;
 
     @CommandLine.Option(
             names = {"-t", "--templates"},
             arity = "1",
             split = ",",
             paramLabel = "template",
             description = "The template names to write content out without '.vm' extension")
     protected List<String> templates;
 
     @CommandLine.Option(
             names = "--internal-javadoc-url",
             paramLabel = "url",
             description = "The base URL for Javadoc generated by this project")
     protected URI internalJavadocUrl = URI.create("apidocs/");
 
     @CommandLine.Option(
             names = "--internal-javadoc-version",
             paramLabel = "version",
             description = "The Javadoc tool version used to generate the internal site")
     protected String internalJavadocVersion = "21";
 
     @CommandLine.Option(
             names = "--external-javadoc-url",
             split = ",",
             paramLabel = "url",
             description = "External Javadoc base URLs used for validated links")
     protected List<URI> externalJavadocUrls = new ArrayList<>();
 
     @CommandLine.Option(
             names = "--internal-javadoc-source-tree",
             paramLabel = "directory",
             description =
                     "Recursively searches each directory tree for .java files and uses each distinct nearest ancestor "
                             + "ending in src/main/java as an aggregate Javadoc source root. May be repeated; defaults to "
                             + "the source processing root")
     protected List<Path> internalJavadocSourceTrees = new ArrayList<>();
 
     @CommandLine.Parameters(index = "0", description = "The root directory to process sources from")
     protected Path rootDirectory;
 
     @CommandLine.Parameters(index = "1", description = "The directory to generate output(s) to")
     protected Path outputDirectory;
 
     @Override
     public Integer call() {
         try {
             rootDirectory = rootDirectory.toAbsolutePath().normalize();
             outputDirectory = outputDirectory.toAbsolutePath().normalize();
 
             System.out.println("Processing sources from " + rootDirectory);
             Path intermediateFile = Files.createTempFile("configuration-keys", ".properties");
             try {
                 runDoclet(intermediateFile);
                 List<Map<String, String>> discoveredKeys = readDiscoveredKeys(intermediateFile);
                 discoveredKeys.sort(Comparator.comparing(e -> e.get(KEY)));
                 render(discoveredKeys);
             } finally {
                 Files.deleteIfExists(intermediateFile);
             }
             return 0;
         } catch (Exception e) {
             e.printStackTrace(System.err);
             return 1;
         }
     }
 
     /**
      * Collects the source files under {@link #rootDirectory} and runs {@link ConfigurationCollectorDoclet} against them,
      * having it write the discovered configuration keys into the given intermediate properties file.
      */
     protected void runDoclet(Path intermediateFile) throws Exception {
         // Only feed javadoc the files that actually declare configuration keys. This keeps the set of types that
         // javadoc must resolve small, avoiding failures caused by unrelated sources referencing dependencies that
         // are not on this module's classpath (e.g. gson, jetty).
         String marker = mode == Mode.maven ? MAVEN_CONFIGURATION_MARKER : CONFIGURATION_MARKER;
         List<Path> javaSourceFiles = findMainJavaSourceFiles(rootDirectory);
         List<File> sourceFiles = javaSourceFiles.stream()
                 .filter(p -> !p.getFileName().toString().equals("module-info.java"))
                 .filter(p -> !p.toString().replace('\\', '/').contains("/maven-resolver-tools/"))
                 .filter(p -> fileContains(p, marker))
                 .map(Path::toFile)
                 .collect(Collectors.toList());
         if (sourceFiles.isEmpty()) {
             throw new IllegalStateException(
                     "No Java sources declaring configuration keys found under " + rootDirectory);
         }
         List<Path> internalJavadocSourceFiles;
         if (internalJavadocSourceTrees.isEmpty()) {
             internalJavadocSourceFiles = javaSourceFiles;
         } else {
             internalJavadocSourceFiles = new ArrayList<>();
             for (Path sourceTree : internalJavadocSourceTrees) {
                 internalJavadocSourceFiles.addAll(findMainJavaSourceFiles(sourceTree));
             }
         }
         // The Javadoc report may be aggregated from a wider source tree than the configuration declarations.
         List<Path> internalJavadocSourceRoots = internalJavadocSourceFiles.stream()
                 .map(CollectConfiguration::findMainJavaSourceRoot)
                 .filter(Objects::nonNull)
                 .distinct()
                 .toList();
 
         DocumentationTool documentationTool = ToolProvider.getSystemDocumentationTool();
         DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<>();
         try (StandardJavaFileManager fileManager =
                 documentationTool.getStandardFileManager(diagnostics, null, StandardCharsets.UTF_8)) {
             // Configure the classpath on the file manager (the -classpath option is not honored when a file manager
             // is supplied to getTask()). Note that under exec:java the project dependencies are on the context
             // classloader, not on the JVM's java.class.path.
             fileManager.setLocation(StandardLocation.CLASS_PATH, resolveClasspath());
 
             Iterable<? extends JavaFileObject> compilationUnits = fileManager.getJavaFileObjectsFromFiles(sourceFiles);
 
             List<String> options = new ArrayList<>(Arrays.asList(
                     "--output",
                     intermediateFile.toString(),
                     "--mode",
                     mode.name(),
                     "--internal-javadoc-url",
                     internalJavadocUrl.toString(),
                     "--internal-javadoc-version",
                     internalJavadocVersion,
                     "-encoding",
                     "UTF-8"));
             for (Path internalJavadocSourceRoot : internalJavadocSourceRoots) {
                 options.add("--internal-javadoc-source-root");
                 options.add(internalJavadocSourceRoot.toString());
             }
             for (URI externalJavadocUrl : externalJavadocUrls) {
                 options.add("--external-javadoc-url");
                 options.add(externalJavadocUrl.toString());
             }
 
             Writer out = new PrintWriter(System.err);
             DocumentationTool.DocumentationTask task = documentationTool.getTask(
                     out, fileManager, diagnostics, ConfigurationCollectorDoclet.class, options, compilationUnits);
             boolean ok = task.call();
             out.flush();
             if (!ok) {
                 diagnostics.getDiagnostics().forEach(d -> System.err.println(d));
                 throw new IllegalStateException("Javadoc doclet execution failed");
             }
         }
     }
 
     private static boolean fileContains(Path path, String marker) {
         try {
             return Files.readString(path, StandardCharsets.UTF_8).contains(marker);
         } catch (IOException e) {
             return false;
         }
     }
 
     private static List<Path> findMainJavaSourceFiles(Path sourceTree) throws IOException {
         try (Stream<Path> stream = Files.walk(sourceTree)) {
             return stream.map(Path::toAbsolutePath)
                     .filter(p -> p.getFileName().toString().endsWith(".java"))
                     .filter(p -> findMainJavaSourceRoot(p) != null)
                     .toList();
         }
     }
 
     private static Path findMainJavaSourceRoot(Path sourceFile) {
         Path suffix = Path.of("src", "main", "java");
         for (Path current = sourceFile.getParent(); current != null; current = current.getParent()) {
             if (current.endsWith(suffix)) {
                 return current;
             }
         }
         return null;
     }
 
     /**
      * Resolves the classpath to use for symbol resolution during the javadoc run. Under {@code exec:java} the project
      * dependencies live on the context classloader (a {@link URLClassLoader}), not on the JVM's
      * {@code java.class.path}, so both sources are combined.
      */
     private static List<File> resolveClasspath() {
         List<File> classpath = new ArrayList<>();
         for (ClassLoader cl = Thread.currentThread().getContextClassLoader(); cl != null; cl = cl.getParent()) {
             if (cl instanceof URLClassLoader) {
                 for (URL url : ((URLClassLoader) cl).getURLs()) {
                     if ("file".equals(url.getProtocol())) {
                         try {
                             classpath.add(new File(url.toURI()));
                         } catch (URISyntaxException e) {
                             classpath.add(new File(url.getPath()));
                         }
                     }
                 }
             }
         }
         for (String element : System.getProperty("java.class.path").split(File.pathSeparator)) {
             classpath.add(new File(element));
         }
         return classpath;
     }
 
     /**
      * Reads back the intermediate properties file produced by {@link ConfigurationCollectorDoclet} into the list of
      * maps consumed by the Velocity templates.
      */
     static List<Map<String, String>> readDiscoveredKeys(Path intermediateFile) throws Exception {
         Properties properties = new Properties();
         try (Reader reader = Files.newBufferedReader(intermediateFile, StandardCharsets.UTF_8)) {
             properties.load(reader);
         }
         int count = Integer.parseInt(properties.getProperty("keys.count", "0"));
         List<Map<String, String>> discoveredKeys = new ArrayList<>(count);
         for (int i = 0; i < count; i++) {
             Map<String, String> entry = new LinkedHashMap<>();
             for (String field : FIELDS) {
                 entry.put(field, properties.getProperty("keys." + i + "." + field, ""));
             }
             discoveredKeys.add(entry);
         }
         return discoveredKeys;
     }
 
     protected void render(List<Map<String, String>> discoveredKeys) throws Exception {
         Properties properties = new Properties();
         properties.setProperty("resource.loaders", "classpath");
         properties.setProperty("resource.loader.classpath.class", ClasspathResourceLoader.class.getName());
         VelocityEngine velocityEngine = new VelocityEngine();
         velocityEngine.init(properties);
 
         VelocityContext context = new VelocityContext();
         context.put("keys", discoveredKeys);
 
         for (String template : templates) {
             Path output = outputDirectory.resolve(template);
             Files.createDirectories(output.getParent());
             System.out.println("Writing out to " + output);
             try (Writer fileWriter = new CachingWriter(output, StandardCharsets.UTF_8)) {
                 velocityEngine.getTemplate(template + ".vm").merge(context, fileWriter);
             }
         }
     }
 }