AdocCatalog.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 java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.DirectoryStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Optional;

/**
 * Finds which library ships a package, for the message a build prints when an include names
 * a path nothing declared ships. Two catalogs, in order: the manifests already in the union,
 * then the local repository, searched by the group prefix of the path. The goal never
 * fetches an undeclared library, because it would have to guess the version and the build
 * would stop being reproducible.
 */
final class AdocCatalog {

    private AdocCatalog() {
    }

    /**
     * A library found to ship the package that holds a path.
     *
     * @param coordinates the library, at the version it was found at
     * @param pkg         the package that holds the path
     */
    record Hit(AdocCoordinates coordinates, AdocPackage pkg) {
    }

    /**
     * Searches the manifests in the union.
     *
     * @param union the union directory
     * @param path  a path relative to the union, with forward slashes
     * @return the library in the union whose manifest ships the path's package
     */
    static Optional<Hit> inUnion(Path union, String path) {
        for (Path manifestFile : unionManifests(union)) {
            AdocManifest manifest = AdocManifest.read(manifestFile);
            Optional<AdocPackage> owner = manifest.packageOwning(path);
            if (owner.isPresent()) {
                String version = stampVersion(manifestFile.resolveSibling(UnionStamp.FILE_NAME));
                return Optional.of(new Hit(new AdocCoordinates(manifest.groupId(),
                        manifest.artifactId(), version), owner.get()));
            }
        }
        return Optional.empty();
    }

    /**
     * Every manifest in the union, {@code META-INF/ike/<group>/<artifact>/manifest.yaml}, in
     * path order.
     *
     * @param union the union directory
     * @return the manifest files
     */
    static List<Path> unionManifests(Path union) {
        List<Path> found = new ArrayList<>();
        Path area = union.resolve(AdocCoordinates.META_INF_IKE);
        if (!Files.isDirectory(area)) {
            return found;
        }
        for (Path group : children(area)) {
            if (!Files.isDirectory(group)) {
                continue;
            }
            for (Path artifact : children(group)) {
                Path manifest = artifact.resolve(AdocManifest.FILE_NAME);
                if (Files.isRegularFile(manifest)) {
                    found.add(manifest);
                }
            }
        }
        return found;
    }

    /**
     * Searches the local repository for an {@code adoc} zip whose manifest ships the path's
     * package. The group of the path, its first segment, names where to look:
     * {@code network.ike.lab/dev/x.adoc} is searched under {@code network/ike/lab}, then under
     * {@code network/ike} and {@code network}, because a library's packages begin with its own
     * group or with a declared prefix of it. The newest version found wins.
     *
     * @param localRepository the local repository root, {@code ~/.m2/repository}
     * @param path            a path relative to the union, with forward slashes
     * @return the library whose zip ships the path's package, at its newest local version
     */
    static Optional<Hit> inLocalRepository(Path localRepository, String path) {
        int slash = path.indexOf('/');
        String group = slash < 0 ? path : path.substring(0, slash);
        List<Hit> hits = new ArrayList<>();
        String[] labels = group.split("\\.");
        for (int depth = labels.length; depth >= 1; depth--) {
            String candidateGroup = String.join(".", List.of(labels).subList(0, depth));
            Path groupDir = localRepository.resolve(candidateGroup.replace('.', '/'));
            if (!Files.isDirectory(groupDir)) {
                continue;
            }
            for (Path artifactDir : children(groupDir)) {
                if (!Files.isDirectory(artifactDir)) {
                    continue;
                }
                String artifactId = artifactDir.getFileName().toString();
                for (Path versionDir : children(artifactDir)) {
                    if (!Files.isDirectory(versionDir)) {
                        continue;
                    }
                    String version = versionDir.getFileName().toString();
                    AdocCoordinates coordinates = new AdocCoordinates(candidateGroup, artifactId, version);
                    for (Path zip : children(versionDir)) {
                        String name = zip.getFileName().toString();
                        if (!name.startsWith(artifactId + "-")
                                || !name.endsWith("-" + AdocCoordinates.CLASSIFIER + "." + AdocCoordinates.TYPE)) {
                            continue;
                        }
                        Optional<AdocManifest> manifest = readQuietly(zip, coordinates);
                        manifest.flatMap(m -> m.packageOwning(path))
                                .ifPresent(pkg -> hits.add(new Hit(coordinates, pkg)));
                        break;
                    }
                }
            }
        }
        return hits.stream().max(Comparator.comparing(h -> h.coordinates().version(), VersionOrder.INSTANCE));
    }

    private static Optional<AdocManifest> readQuietly(Path zip, AdocCoordinates coordinates) {
        try {
            return AdocManifest.readFromZip(zip, coordinates);
        } catch (RuntimeException e) {
            // A zip that cannot be read or whose manifest is malformed is not a candidate.
            return Optional.empty();
        }
    }

    private static String stampVersion(Path stamp) {
        try {
            return UnionStamp.read(stamp).map(UnionStamp::version).filter(v -> !v.isBlank()).orElse("unknown");
        } catch (IOException e) {
            return "unknown";
        }
    }

    private static List<Path> children(Path dir) {
        List<Path> result = new ArrayList<>();
        try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
            stream.forEach(result::add);
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
        result.sort(Comparator.comparing(p -> p.getFileName().toString()));
        return result;
    }
}