AdocUnion.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.adoc;

import org.apache.maven.api.plugin.Log;
import org.apache.maven.api.plugin.MojoException;

import java.io.IOException;
import java.io.InputStream;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.StandardCopyOption;
import java.nio.file.attribute.BasicFileAttributes;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.HexFormat;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
import java.util.stream.Stream;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;

/**
 * One union of AsciiDoc packages per repository, written and verified from any module of
 * it. The union mirrors every declared library's root: a package such as
 * {@code network.ike.lab/dev} is copied from an external library's zip, or linked to a
 * reactor member's {@code src/docs/asciidoc/network.ike.lab/dev} so an edit reached through
 * an include changes the real source. Each library's manifest and a stamp are under
 * {@code META-INF/ike/<group>/<artifact>/}, which is how a later run knows what is there.
 *
 * <p>The rules, in the order they are applied:
 * <ul>
 *   <li>A zip without a manifest is a legacy library. With legacy mode on it is unpacked
 *       into the legacy per-module directory as the stock unpack did; otherwise the build
 *       refuses, naming the artifact.</li>
 *   <li>Two libraries that ship one package are refused, naming both. A library already in
 *       the union that no module declares anymore counts too, since the union is one per
 *       repository.</li>
 *   <li>An unchanged library is not rewritten: a copy is keyed by the zip's SHA-256, a link
 *       by its target.</li>
 *   <li>A stale entry whose library is not among those declared is left alone; a run writes
 *       only the libraries it was given.</li>
 * </ul>
 *
 * <p>Whether IntelliJ resolves includes, previews and navigates through a symbolic link in
 * {@code target/generated-sources} is to be confirmed by KEC on one machine; until then the
 * link stays the default and {@code link=false} copies a member's tree instead.
 */
public final class AdocUnion {

    /**
     * What one run did, by library.
     *
     * @param copied    external libraries copied from their zip
     * @param linked    reactor members linked, or copied from their tree when linking is off
     * @param unchanged libraries already in the union as they are
     * @param legacy    legacy libraries unpacked into the legacy directory
     */
    public record Result(List<AdocCoordinates> copied, List<AdocCoordinates> linked,
                         List<AdocCoordinates> unchanged, List<AdocCoordinates> legacy) {

        /**
         * One line for the build log.
         *
         * @return the counts, in plain words
         */
        public String summary() {
            return copied.size() + " copied, " + linked.size() + " linked, " + unchanged.size()
                    + " unchanged" + (legacy.isEmpty() ? "" : ", " + legacy.size() + " legacy");
        }
    }

    private final Path unionDirectory;
    private final Path legacyDirectory;
    private final boolean link;
    private final boolean legacy;
    private final Log log;
    private boolean legacyUnpacked;

    /**
     * A union at a directory.
     *
     * @param unionDirectory  the union, {@code <reactor root>/target/generated-sources/adoc}
     * @param legacyDirectory where a legacy library is unpacked when legacy mode is on
     * @param link            link a reactor member's packages rather than copying them
     * @param legacy          unpack a zip without a manifest rather than refusing it
     * @param log             the build log
     */
    public AdocUnion(Path unionDirectory, Path legacyDirectory, boolean link, boolean legacy, Log log) {
        this.unionDirectory = unionDirectory.toAbsolutePath().normalize();
        this.legacyDirectory = legacyDirectory.toAbsolutePath().normalize();
        this.link = link;
        this.legacy = legacy;
        this.log = log;
    }

    /**
     * The union directory.
     *
     * @return the absolute, normalized union directory
     */
    public Path unionDirectory() {
        return unionDirectory;
    }

    /**
     * Whether {@link #update} unpacked a legacy library into the legacy directory.
     *
     * @return true after a legacy unpack in this run
     */
    public boolean legacyUnpacked() {
        return legacyUnpacked;
    }

    /**
     * Puts the given libraries in the union, each according to the rules above.
     *
     * @param libraries the libraries one module declares, plus the module itself when it is
     *                  a library
     * @return what was done
     * @throws MojoException on a legacy zip outside legacy mode, two libraries shipping one
     *                       package, a manifest that names other coordinates than the
     *                       dependency, or a file that cannot be written
     */
    public Result update(List<AdocLibrary> libraries) {
        try {
            Files.createDirectories(unionDirectory);
            Map<AdocLibrary, AdocManifest> manifests = new LinkedHashMap<>();
            List<AdocLibrary> legacyLibraries = new ArrayList<>();
            for (AdocLibrary library : libraries) {
                if (library.isReactor()) {
                    manifests.put(library, AdocManifest.fromSourceTree(library.coordinates(), library.sourceRoot()));
                    continue;
                }
                Optional<AdocManifest> manifest = AdocManifest.readFromZip(library.zip(), library.coordinates());
                if (manifest.isPresent()) {
                    if (!manifest.get().ga().equals(library.coordinates().ga())) {
                        throw new MojoException("The manifest in " + library.zip() + " names "
                                + manifest.get().ga() + " but the dependency is " + library.coordinates().ga());
                    }
                    manifests.put(library, manifest.get());
                } else if (legacy) {
                    legacyLibraries.add(library);
                } else {
                    throw new MojoException(library.coordinates().gav() + " ships no "
                            + library.coordinates().manifestPath() + ": it is a legacy library with the"
                            + " topics/ layout. Rebuild it with the package layout, or unpack it as before"
                            + " into " + legacyDirectory + " with -Dike.adoc.legacy=true.");
                }
            }
            refuseSplitPackages(manifests);

            List<AdocCoordinates> copied = new ArrayList<>();
            List<AdocCoordinates> linked = new ArrayList<>();
            List<AdocCoordinates> unchanged = new ArrayList<>();
            List<AdocCoordinates> legacyDone = new ArrayList<>();
            for (Map.Entry<AdocLibrary, AdocManifest> entry : manifests.entrySet()) {
                AdocLibrary library = entry.getKey();
                boolean changed = library.isReactor()
                        ? (link ? linkMember(library, entry.getValue()) : copyTree(library, entry.getValue()))
                        : copyZip(library, entry.getValue());
                (changed ? (library.isReactor() ? linked : copied) : unchanged).add(library.coordinates());
            }
            for (AdocLibrary library : legacyLibraries) {
                unpackLegacy(library);
                legacyDone.add(library.coordinates());
            }
            return new Result(copied, linked, unchanged, legacyDone);
        } catch (IOException | UncheckedIOException e) {
            throw new MojoException("Cannot write the AsciiDoc union at " + unionDirectory + ": " + e.getMessage(), e);
        }
    }

    /**
     * Checks that every {@code {adoc}} and {@code {topics}} include under a module's own
     * AsciiDoc source root resolves in the union. An include into the legacy directory
     * through {@code {topics}} also resolves while a legacy library was unpacked there. An
     * unresolved include fails the build with the library that ships the package and the
     * exact dependency block to add, found in the union's manifests, then in the local
     * repository; nothing is fetched.
     *
     * @param sourceDirectory the module's {@code src/docs/asciidoc}
     * @param localRepository the local repository root, searched for the suggestion
     * @return the number of includes that resolved
     * @throws MojoException when an include does not resolve
     */
    public int verifyIncludes(Path sourceDirectory, Path localRepository) {
        List<IncludeReference> references = IncludeScanner.scan(sourceDirectory);
        List<String> problems = new ArrayList<>();
        int checked = 0;
        for (IncludeReference reference : references) {
            if (reference.path().indexOf('{') >= 0) {
                // An attribute inside the path is the renderer's to expand.
                continue;
            }
            checked++;
            if (!resolves(reference)) {
                problems.add(describe(reference, sourceDirectory, localRepository));
            }
        }
        if (!problems.isEmpty()) {
            StringBuilder message = new StringBuilder();
            message.append(problems.size()).append(problems.size() == 1 ? " include" : " includes")
                    .append(" in ").append(sourceDirectory).append(problems.size() == 1 ? " does" : " do")
                    .append(" not resolve in the AsciiDoc union ").append(unionDirectory).append(":\n");
            problems.forEach(message::append);
            throw new MojoException(message.toString());
        }
        return checked;
    }

    private boolean resolves(IncludeReference reference) {
        Path inUnion = unionDirectory.resolve(reference.path()).normalize();
        if (inUnion.startsWith(unionDirectory) && Files.exists(inUnion)) {
            return true;
        }
        if ("topics".equals(reference.attribute()) && Files.isDirectory(legacyDirectory)) {
            Path inLegacy = legacyDirectory.resolve(reference.path()).normalize();
            return inLegacy.startsWith(legacyDirectory) && Files.exists(inLegacy);
        }
        return false;
    }

    private String describe(IncludeReference reference, Path sourceDirectory, Path localRepository) {
        Path shown = sourceDirectory.toAbsolutePath().normalize().relativize(
                reference.file().toAbsolutePath().normalize());
        StringBuilder out = new StringBuilder();
        out.append("  ").append(shown).append(':').append(reference.line()).append("  ")
                .append(reference.asWritten()).append('\n');
        Optional<AdocCatalog.Hit> inUnion = AdocCatalog.inUnion(unionDirectory, reference.path());
        if (inUnion.isPresent()) {
            AdocCatalog.Hit hit = inUnion.get();
            out.append("    ").append(hit.coordinates().ga()).append(" (version ")
                    .append(hit.coordinates().version()).append(") is in the union and ships the package ")
                    .append(hit.pkg().name()).append(", but not this file. Check the path.\n");
            return out.toString();
        }
        Optional<AdocCatalog.Hit> local = localRepository == null ? Optional.empty()
                : AdocCatalog.inLocalRepository(localRepository, reference.path());
        if (local.isPresent()) {
            AdocCatalog.Hit hit = local.get();
            out.append("    ").append(hit.coordinates().ga()).append(" ships the package ")
                    .append(hit.pkg().name()).append(" (version ").append(hit.coordinates().version())
                    .append(" in the local repository). Add it to this module's pom.xml:\n")
                    .append(hit.coordinates().dependencyBlock());
            return out.toString();
        }
        out.append("    No library in the union or in the local repository ships a package holding ")
                .append(reference.path()).append(". Declare the library that ships it; the build never")
                .append(" fetches an undeclared library.\n");
        return out.toString();
    }

    // ── exclusivity ──────────────────────────────────────────────────────

    private void refuseSplitPackages(Map<AdocLibrary, AdocManifest> manifests) {
        Map<String, AdocCoordinates> owners = new HashMap<>();
        Set<String> declared = new HashSet<>();
        for (Map.Entry<AdocLibrary, AdocManifest> entry : manifests.entrySet()) {
            AdocCoordinates coordinates = entry.getKey().coordinates();
            declared.add(coordinates.ga());
            for (AdocPackage pkg : entry.getValue().packages()) {
                AdocCoordinates other = owners.putIfAbsent(pkg.name(), coordinates);
                if (other != null && !other.ga().equals(coordinates.ga())) {
                    throw new MojoException("Two libraries ship the package " + pkg.name() + ": "
                            + other.gav() + " and " + coordinates.gav()
                            + ". A package has one owner; rename or move it in one of them.");
                }
            }
        }
        for (Path manifestFile : AdocCatalog.unionManifests(unionDirectory)) {
            AdocManifest existing = AdocManifest.read(manifestFile);
            if (declared.contains(existing.ga())) {
                continue;
            }
            for (AdocPackage pkg : existing.packages()) {
                AdocCoordinates incoming = owners.get(pkg.name());
                if (incoming != null) {
                    throw new MojoException("Two libraries ship the package " + pkg.name() + ": "
                            + existing.ga() + ", already in the union at " + unionDirectory
                            + " and declared by no module of this build, and " + incoming.gav()
                            + ". If " + existing.ga() + " is no longer used, delete "
                            + manifestFile.getParent() + " and the package, or clean the root.");
                }
            }
        }
    }

    // ── one library ──────────────────────────────────────────────────────

    private boolean copyZip(AdocLibrary library, AdocManifest manifest) throws IOException {
        AdocCoordinates coordinates = library.coordinates();
        Path meta = unionDirectory.resolve(coordinates.metaInfPath());
        Path stampFile = meta.resolve(UnionStamp.FILE_NAME);
        String sha256 = sha256(library.zip());
        Optional<UnionStamp> stamp = UnionStamp.read(stampFile);
        if (stamp.isPresent() && UnionStamp.MODE_COPY.equals(stamp.get().mode())
                && sha256.equals(stamp.get().sha256())
                && Files.isRegularFile(meta.resolve(AdocManifest.FILE_NAME))) {
            log.debug("adoc-union: " + coordinates.gav() + " unchanged");
            return false;
        }
        removeEntry(meta);
        extract(library.zip(), unionDirectory);
        for (AdocPackage pkg : manifest.packages()) {
            if (!Files.isDirectory(unionDirectory.resolve(pkg.name()))) {
                log.warn("adoc-union: " + coordinates.gav() + " lists the package " + pkg.name()
                        + " in its manifest but ships no such directory");
            }
        }
        new UnionStamp(coordinates.version(), UnionStamp.MODE_COPY, library.zip().toString(), sha256)
                .write(stampFile);
        log.info("adoc-union: copied " + coordinates.gav() + " (" + manifest.packages().size()
                + " packages) into " + unionDirectory);
        return true;
    }

    private boolean linkMember(AdocLibrary library, AdocManifest manifest) throws IOException {
        AdocCoordinates coordinates = library.coordinates();
        Path meta = unionDirectory.resolve(coordinates.metaInfPath());
        boolean changed = dropPackagesNoLongerShipped(meta, manifest);
        for (AdocPackage pkg : manifest.packages()) {
            Path target = library.sourceRoot().resolve(pkg.name()).toAbsolutePath().normalize();
            Path at = unionDirectory.resolve(pkg.name());
            if (Files.isSymbolicLink(at) && Files.readSymbolicLink(at).equals(target)) {
                continue;
            }
            deleteTree(at);
            Files.createDirectories(at.getParent());
            Files.createSymbolicLink(at, target);
            changed = true;
        }
        changed |= writeIfDifferent(meta.resolve(AdocManifest.FILE_NAME), manifest.toYaml());
        changed |= writeStampIfDifferent(meta.resolve(UnionStamp.FILE_NAME), new UnionStamp(
                coordinates.version(), UnionStamp.MODE_LINK, library.sourceRoot().toString(), null));
        if (changed) {
            log.info("adoc-union: linked " + coordinates.gav() + " (" + manifest.packages().size()
                    + " packages) from " + library.sourceRoot());
        } else {
            log.debug("adoc-union: " + coordinates.gav() + " unchanged");
        }
        return changed;
    }

    private boolean copyTree(AdocLibrary library, AdocManifest manifest) throws IOException {
        AdocCoordinates coordinates = library.coordinates();
        Path meta = unionDirectory.resolve(coordinates.metaInfPath());
        boolean changed = dropPackagesNoLongerShipped(meta, manifest);
        for (AdocPackage pkg : manifest.packages()) {
            Path source = library.sourceRoot().resolve(pkg.name());
            Path at = unionDirectory.resolve(pkg.name());
            if (Files.isSymbolicLink(at)) {
                Files.delete(at);
                changed = true;
            }
            changed |= syncDirectory(source, at);
        }
        changed |= writeIfDifferent(meta.resolve(AdocManifest.FILE_NAME), manifest.toYaml());
        changed |= writeStampIfDifferent(meta.resolve(UnionStamp.FILE_NAME), new UnionStamp(
                coordinates.version(), UnionStamp.MODE_TREE, library.sourceRoot().toString(), null));
        if (changed) {
            log.info("adoc-union: copied " + coordinates.gav() + " (" + manifest.packages().size()
                    + " packages) from " + library.sourceRoot());
        } else {
            log.debug("adoc-union: " + coordinates.gav() + " unchanged");
        }
        return changed;
    }

    private void unpackLegacy(AdocLibrary library) throws IOException {
        Files.createDirectories(legacyDirectory);
        extract(library.zip(), legacyDirectory);
        legacyUnpacked = true;
        log.warn("adoc-union: " + library.coordinates().gav() + " is a legacy library; unpacked into "
                + legacyDirectory + " (ike.adoc.legacy=true)");
    }

    /** Removes the packages an earlier manifest listed that the new one no longer ships. */
    private boolean dropPackagesNoLongerShipped(Path meta, AdocManifest manifest) throws IOException {
        Path manifestFile = meta.resolve(AdocManifest.FILE_NAME);
        if (!Files.isRegularFile(manifestFile)) {
            return false;
        }
        Set<String> kept = new HashSet<>();
        manifest.packages().forEach(p -> kept.add(p.name()));
        boolean changed = false;
        for (AdocPackage old : AdocManifest.read(manifestFile).packages()) {
            if (!kept.contains(old.name())) {
                changed |= deleteTree(unionDirectory.resolve(old.name()));
            }
        }
        return changed;
    }

    /** Removes a library's packages, as its manifest in the union lists them, and its META-INF area. */
    private void removeEntry(Path meta) throws IOException {
        Path manifestFile = meta.resolve(AdocManifest.FILE_NAME);
        if (Files.isRegularFile(manifestFile)) {
            for (AdocPackage old : AdocManifest.read(manifestFile).packages()) {
                deleteTree(unionDirectory.resolve(old.name()));
            }
        }
        deleteTree(meta);
    }

    // ── files ────────────────────────────────────────────────────────────

    private static void extract(Path zip, Path into) throws IOException {
        Path root = into.toAbsolutePath().normalize();
        try (ZipInputStream in = new ZipInputStream(Files.newInputStream(zip))) {
            ZipEntry entry;
            while ((entry = in.getNextEntry()) != null) {
                Path target = root.resolve(entry.getName()).normalize();
                if (!target.startsWith(root)) {
                    throw new IOException("Zip entry outside the target directory: " + entry.getName() + " in " + zip);
                }
                if (entry.isDirectory()) {
                    Files.createDirectories(target);
                } else {
                    Files.createDirectories(target.getParent());
                    if (Files.isSymbolicLink(target)) {
                        Files.delete(target);
                    }
                    Files.copy(in, target, StandardCopyOption.REPLACE_EXISTING);
                }
                in.closeEntry();
            }
        }
    }

    /** Makes {@code into} hold exactly the files of {@code from}; returns whether anything changed. */
    private static boolean syncDirectory(Path from, Path into) throws IOException {
        boolean changed = false;
        Set<Path> wanted = new HashSet<>();
        if (Files.isDirectory(from)) {
            try (Stream<Path> walk = Files.walk(from)) {
                for (Path source : walk.filter(Files::isRegularFile).toList()) {
                    Path relative = from.relativize(source);
                    Path target = into.resolve(relative.toString());
                    wanted.add(target);
                    if (!Files.isRegularFile(target)
                            || Files.size(target) != Files.size(source)
                            || !Files.getLastModifiedTime(target).equals(Files.getLastModifiedTime(source))) {
                        Files.createDirectories(target.getParent());
                        Files.copy(source, target, StandardCopyOption.REPLACE_EXISTING,
                                StandardCopyOption.COPY_ATTRIBUTES);
                        changed = true;
                    }
                }
            }
        }
        if (Files.isDirectory(into)) {
            try (Stream<Path> walk = Files.walk(into)) {
                for (Path present : walk.filter(Files::isRegularFile).toList()) {
                    if (!wanted.contains(present)) {
                        Files.delete(present);
                        changed = true;
                    }
                }
            }
        }
        return changed;
    }

    /** Deletes a file, a symbolic link without following it, or a whole directory. */
    private static boolean deleteTree(Path path) throws IOException {
        if (Files.isSymbolicLink(path) || Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)) {
            Files.delete(path);
            return true;
        }
        if (!Files.isDirectory(path, LinkOption.NOFOLLOW_LINKS)) {
            return false;
        }
        Files.walkFileTree(path, new SimpleFileVisitor<>() {
            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException {
                Files.delete(file);
                return FileVisitResult.CONTINUE;
            }

            @Override
            public FileVisitResult postVisitDirectory(Path dir, IOException exc) throws IOException {
                if (exc != null) {
                    throw exc;
                }
                Files.delete(dir);
                return FileVisitResult.CONTINUE;
            }
        });
        return true;
    }

    private static boolean writeIfDifferent(Path file, String content) throws IOException {
        if (Files.isRegularFile(file) && Files.readString(file, StandardCharsets.UTF_8).equals(content)) {
            return false;
        }
        Files.createDirectories(file.getParent());
        Files.writeString(file, content, StandardCharsets.UTF_8);
        return true;
    }

    private static boolean writeStampIfDifferent(Path file, UnionStamp stamp) throws IOException {
        if (UnionStamp.read(file).filter(stamp::equals).isPresent()) {
            return false;
        }
        stamp.write(file);
        return true;
    }

    private static String sha256(Path file) throws IOException {
        try (InputStream in = Files.newInputStream(file)) {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            byte[] buffer = new byte[1 << 16];
            int read;
            while ((read = in.read(buffer)) >= 0) {
                digest.update(buffer, 0, read);
            }
            return HexFormat.of().formatHex(digest.digest());
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException(e);
        }
    }
}