AdocUnionMojo.java

/*
 * Copyright © 2026 IKE Network (support@ike.network)
 *
 * Licensed 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 network.ike.plugin;

import network.ike.plugin.adoc.AdocCoordinates;
import network.ike.plugin.adoc.AdocLibrary;
import network.ike.plugin.adoc.AdocManifest;
import network.ike.plugin.adoc.AdocUnion;
import network.ike.plugin.adoc.ReactorLayout;
import network.ike.plugin.adoc.RootConfig;
import org.apache.maven.api.Dependency;
import org.apache.maven.api.Node;
import org.apache.maven.api.PathScope;
import org.apache.maven.api.Project;
import org.apache.maven.api.Session;
import org.apache.maven.api.di.Inject;
import org.apache.maven.api.plugin.Log;
import org.apache.maven.api.plugin.MojoException;
import org.apache.maven.api.plugin.annotations.Mojo;
import org.apache.maven.api.plugin.annotations.Parameter;
import org.apache.maven.api.services.ProjectManager;

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.locks.ReentrantLock;

/**
 * Unpacks every topic library a module declares into one AsciiDoc union per repository,
 * {@code <reactor root>/target/generated-sources/adoc}, and checks that the module's own
 * includes resolve there (IKE-Network/ike-issues#1342; design topic {@code dev-adoc-packages}
 * in ike-lab-documents). It replaces the stock {@code unpack-dependencies} execution for
 * {@code adoc} zips.
 *
 * <p>A library lays its root out as packages, {@code <group>/<domain>/<topic>.adoc}, and ships
 * a manifest at {@code META-INF/ike/<group>/<artifact>/manifest.yaml} listing them. The goal:
 * <ul>
 *   <li>resolves the module's dependencies with classifier {@code adoc} and type {@code zip},
 *       transitively, as {@code unpack-dependencies} does;</li>
 *   <li>copies an external library's content from its zip, and links the package directories
 *       of a library that is a module of the same reactor to its {@code src/docs/asciidoc},
 *       so an edit reached through an include changes the real source
 *       ({@code ike.adoc.link}, default true). Whether IntelliJ resolves includes, previews
 *       and navigates through such a link is to be confirmed by KEC on one machine;</li>
 *   <li>treats a zip without a manifest as a legacy library: refused, naming the artifact,
 *       unless {@code ike.adoc.legacy=true}, which unpacks it into the legacy per-module
 *       directory as before;</li>
 *   <li>refuses two libraries that ship one package, naming both;</li>
 *   <li>is idempotent from every module, so a {@code -pl} build works: an unchanged library
 *       is not rewritten, and an entry whose library no module declares anymore is left
 *       alone, since the union is per repository and not per module;</li>
 *   <li>verifies that every {@code include::{adoc}/...} and {@code include::{topics}/...} in
 *       the module's {@code src/docs/asciidoc} resolves in the union, and fails the build for
 *       one that does not with the exact {@code <dependency>} block to add, found in the
 *       union's manifests and then in the local repository by the group prefix of the path.
 *       It never fetches an undeclared library;</li>
 *   <li>sets the project properties {@code adoc} and {@code topics} to the union, so the
 *       asciidoctor plugin's attributes can reference them. While a legacy library was
 *       unpacked, {@code topics} names the legacy directory instead, so the old include
 *       lines keep resolving until the last consumer migrates.</li>
 * </ul>
 *
 * <p>The module itself, when its own source root has the package layout, is linked into the
 * union too, so a library's own {@code {adoc}} includes resolve in a build of that module
 * alone.
 *
 * <p>Typical wiring, in ike-parent (IKE-Network/ike-issues#1343):
 *
 * <pre>{@code
 * <execution>
 *     <id>adoc-union</id>
 *     <phase>generate-sources</phase>
 *     <goals><goal>adoc-union</goal></goals>
 * </execution>
 * }</pre>
 *
 * <p>Modules of a {@code -T} reactor share the union, so the goal serializes its writes
 * JVM-wide.
 *
 * @since 276
 */
@Mojo(name = IkeGoal.NAME_ADOC_UNION,
      defaultPhase = "generate-sources")
public class AdocUnionMojo implements org.apache.maven.api.plugin.Mojo {

    /** The project property set to the union directory, which the {@code {adoc}} attribute reads. */
    public static final String PROPERTY_ADOC = "adoc";

    /** The project property set for the {@code {topics}} alias, which the migration keeps. */
    public static final String PROPERTY_TOPICS = "topics";

    /** The AsciiDoc source root under a module. */
    static final String SOURCE_ROOT = "src/docs/asciidoc";

    private static final ReentrantLock UNION_LOCK = new ReentrantLock();

    /** Creates this goal instance. */
    public AdocUnionMojo() {}

    @Inject
    private Log log;

    @Inject
    private Session session;

    @Inject
    private Project project;

    /**
     * The union directory, one per repository. Defaults to
     * {@code <reactor root>/target/generated-sources/adoc}: the reactor root is the directory
     * holding {@code .mvn} or the pom flagged {@code root="true"}. Three levels under the root
     * is deliberate: IntelliJ registers every immediate subfolder of
     * {@code target/generated-sources} as a source root, which is what gets the union
     * indexed for anchor navigation.
     */
    @Parameter(property = "ike.adoc.union")
    String unionDirectory;

    /**
     * Link the package directories of a library that is a module of the same reactor to its
     * {@code src/docs/asciidoc}, rather than copying them. Off, the member's tree is copied
     * and kept in sync.
     */
    @Parameter(property = "ike.adoc.link", defaultValue = "true")
    boolean link;

    /**
     * Unpack a zip that ships no manifest, a legacy library, into
     * {@link #legacyDirectory} as the stock unpack did. Off, such a zip fails the build.
     */
    @Parameter(property = "ike.adoc.legacy", defaultValue = "false")
    boolean legacy;

    /**
     * Where a legacy library is unpacked when {@link #legacy} is on: the per-module
     * directory the stock unpack used.
     */
    @Parameter(property = "ike.adoc.legacyDirectory",
               defaultValue = "${project.build.directory}/generated-sources/asciidoc/topics-asciidoc")
    String legacyDirectory;

    /**
     * The module's AsciiDoc source root, whose includes are verified against the union.
     */
    @Parameter(property = "ike.adoc.sourceDirectory", defaultValue = "${project.basedir}/" + SOURCE_ROOT)
    String sourceDirectory;

    /**
     * Verify that every {@code {adoc}} and {@code {topics}} include in the source root
     * resolves in the union, failing the build for one that does not.
     */
    @Parameter(property = "ike.adoc.verifyIncludes", defaultValue = "true")
    boolean verifyIncludes;

    /** Skip the goal. The properties are then not set. */
    @Parameter(property = "ike.adoc.skip", defaultValue = "false")
    boolean skip;

    /**
     * Resolves the declared libraries, updates the union, verifies the module's includes and
     * sets the {@code adoc} and {@code topics} properties.
     *
     * @throws MojoException on a legacy library outside legacy mode, two libraries shipping one
     *                       package, an include that does not resolve, or a file that cannot
     *                       be written
     */
    @Override
    public void execute() {
        if (skip) {
            log.info("ike:adoc-union skipped (ike.adoc.skip=true)");
            return;
        }
        Path union = resolveUnionDirectory();
        Path legacyDir = Path.of(legacyDirectory).toAbsolutePath().normalize();
        Path source = Path.of(sourceDirectory).toAbsolutePath().normalize();

        List<AdocLibrary> libraries = declaredLibraries();
        selfLibrary(source).ifPresent(libraries::add);

        AdocUnion.Result result;
        int verified = 0;
        boolean legacyUsed;
        UNION_LOCK.lock();
        try {
            AdocUnion adocUnion = new AdocUnion(union, legacyDir, link, legacy, log);
            result = adocUnion.update(libraries);
            if (verifyIncludes) {
                verified = adocUnion.verifyIncludes(source, session.getLocalRepository().getPath());
            }
            legacyUsed = adocUnion.legacyUnpacked();
            installRootConfig();
        } finally {
            UNION_LOCK.unlock();
        }

        ProjectManager projectManager = session.getService(ProjectManager.class);
        projectManager.setProperty(project, PROPERTY_ADOC, union.toString());
        projectManager.setProperty(project, PROPERTY_TOPICS, (legacyUsed ? legacyDir : union).toString());

        log.info("ike:adoc-union: " + libraries.size() + " libraries in " + union + " (" + result.summary()
                + "); " + verified + " includes verified; " + PROPERTY_ADOC + "=" + union
                + (legacyUsed ? "; " + PROPERTY_TOPICS + "=" + legacyDir : ""));
    }

    /**
     * The repository's one {@code .asciidoctorconfig}, from the classifier zip the doc pipeline
     * declares. Here, under the union's lock, because every module with AsciiDoc sources would
     * write the one file, and a stock unpack in two modules at once fails a {@code -T} build.
     * A module that does not declare the zip leaves the file as it is.
     */
    private void installRootConfig() {
        List<Node> nodes = RuntimeClasspathResolver.serialized(session, () -> session.flattenDependencies(
                session.collectDependencies(project, PathScope.MAIN_COMPILE), PathScope.MAIN_COMPILE));
        for (Node node : nodes) {
            Dependency dependency = node.getDependency();
            if (dependency == null || !RootConfig.CLASSIFIER.equals(dependency.getClassifier())) {
                continue;
            }
            try {
                Path zip = RuntimeClasspathResolver.serialized(session, () -> session.resolveArtifact(dependency).getPath());
                if (RootConfig.install(zip, reactorRoot())) {
                    log.info("ike:adoc-union: wrote " + reactorRoot().resolve(RootConfig.FILE_NAME));
                }
            } catch (java.io.IOException | RuntimeException e) {
                throw new MojoException("Cannot install " + RootConfig.FILE_NAME + ": " + e.getMessage(), e);
            }
            return;
        }
    }

    private Path resolveUnionDirectory() {
        if (unionDirectory != null && !unionDirectory.isBlank()) {
            return Path.of(unionDirectory).toAbsolutePath().normalize();
        }
        return reactorRoot().resolve("target").resolve("generated-sources").resolve("adoc").toAbsolutePath().normalize();
    }

    /**
     * The module's dependencies with classifier {@code adoc} and type {@code zip}, transitive
     * ones included. One that is a module of this reactor, with a source root on disk, is a
     * reactor member: found among the session's projects, or, in a {@code -pl} build that
     * left it out, by its pom under the reactor root. Every other is resolved to its zip.
     */
    private List<AdocLibrary> declaredLibraries() {
        Path root = reactorRoot();
        // Collection goes through the plugin's serialized entry point — Maven 4 rc-5's
        // resolver cache is not thread-safe under -T (IKE-Network/ike-issues#901).
        List<Node> nodes = RuntimeClasspathResolver.serialized(session, () -> session.flattenDependencies(
                session.collectDependencies(project, PathScope.MAIN_COMPILE), PathScope.MAIN_COMPILE));
        List<AdocLibrary> libraries = new ArrayList<>();
        for (Node node : nodes) {
            Dependency dependency = node.getDependency();
            if (dependency == null
                    || !AdocCoordinates.CLASSIFIER.equals(dependency.getClassifier())
                    || !AdocCoordinates.TYPE.equals(dependency.getExtension())) {
                continue;
            }
            AdocCoordinates coordinates = new AdocCoordinates(dependency.getGroupId(),
                    dependency.getArtifactId(), dependency.getVersion().toString());
            Optional<Path> memberDir = memberBasedir(root, coordinates);
            if (memberDir.isPresent()) {
                Path sourceRoot = memberDir.get().resolve(SOURCE_ROOT);
                if (Files.isDirectory(sourceRoot)) {
                    libraries.add(AdocLibrary.reactor(coordinates, sourceRoot));
                    continue;
                }
                log.warn("ike:adoc-union: reactor member " + coordinates.gav() + " has no " + sourceRoot
                        + "; resolving it from the repository");
            }
            Path zip;
            try {
                zip = session.resolveArtifact(dependency).getPath();
            } catch (RuntimeException e) {
                throw new MojoException("Cannot resolve the topic library " + coordinates.gav() + ": "
                        + e.getMessage(), e);
            }
            libraries.add(AdocLibrary.external(coordinates, zip));
        }
        return libraries;
    }

    /**
     * The directory of the reactor module with these coordinates: one of the session's
     * projects at the same version, else one found by its pom under the reactor root, which
     * is how a sibling left out of a {@code -pl} build is still linked rather than copied
     * from a stale zip.
     */
    private Optional<Path> memberBasedir(Path root, AdocCoordinates coordinates) {
        Optional<Project> inSession = session.getProjects().stream()
                .filter(p -> p.getGroupId().equals(coordinates.groupId())
                        && p.getArtifactId().equals(coordinates.artifactId()))
                .findFirst();
        if (inSession.isPresent()) {
            Project member = inSession.get();
            if (member.getVersion().equals(coordinates.version())) {
                return Optional.of(member.getBasedir());
            }
            log.warn("ike:adoc-union: " + coordinates.gav() + " is declared at a version other than"
                    + " the reactor's " + member.getVersion() + "; resolving it from the repository");
            return Optional.empty();
        }
        return ReactorLayout.memberBasedir(root, coordinates.groupId(), coordinates.artifactId());
    }

    private Path reactorRoot() {
        try {
            return project.getRootDirectory();
        } catch (IllegalStateException e) {
            return session.getTopDirectory();
        }
    }

    /** This module as a library of the union, when its own source root has the package layout. */
    private Optional<AdocLibrary> selfLibrary(Path source) {
        AdocCoordinates self = new AdocCoordinates(project.getGroupId(), project.getArtifactId(), project.getVersion());
        if (Files.isDirectory(source) && !AdocManifest.fromSourceTree(self, source).packages().isEmpty()) {
            return Optional.of(AdocLibrary.reactor(self, source));
        }
        return Optional.empty();
    }
}