PackageLint.java

package network.ike.docs.plugin.packages;

import network.ike.docs.plugin.registry.TopicHeader;
import network.ike.docs.plugin.registry.TopicRegistry;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;

/**
 * The ownership lint of the packages layout ({@code dev-adoc-packages},
 * IKE-Network/ike-issues#1341), the check that makes the layout a
 * guarantee and not a habit. It fails the build with every finding listed:
 *
 * <ul>
 *   <li>the root holds nothing but dotted-group directories and
 *       {@code META-INF}: a file at the root, an {@code images} directory
 *       at the root, or a directory that is not a group is a finding;</li>
 *   <li>every package begins with the module's own group, unless
 *       {@code ike.adoc.packages} declares another prefix on purpose;</li>
 *   <li>a topic's directory equals the domain prefix of its
 *       {@code :topic-id:}, so that a person who knows a topic's id and its
 *       owner can write its include line without looking;</li>
 *   <li>images are inside packages: an {@code images} directory directly
 *       under a group that is not itself a package is a finding.</li>
 * </ul>
 *
 * <p>An include or image line that still uses the {@code {topics}} alias
 * is reported as a warning naming the file and line, so the alias can be
 * retired once the last one is gone; it does not fail the build.
 *
 * @since 136
 */
public final class PackageLint {

    /** The include attribute of the packages layout. */
    public static final String ATTRIBUTE = "{adoc}";

    /** The migration alias the lint reports. */
    public static final String ALIAS = "{topics}";

    /**
     * What the lint found.
     *
     * @param errors   findings that fail the build, in the order found
     * @param warnings findings that do not, in the order found
     */
    public record Report(List<String> errors, List<String> warnings) {

        /**
         * Whether the build passes.
         *
         * @return true when there is no error
         */
        public boolean clean() {
            return errors.isEmpty();
        }
    }

    private PackageLint() {
    }

    /**
     * Lint a root.
     *
     * @param root     the AsciiDoc root
     * @param groupId  the module's group id, which every package begins with
     * @param declared package names or group prefixes
     *                 {@code ike.adoc.packages} declares on purpose; a package
     *                 passes the ownership rule when it equals one or begins
     *                 with one followed by {@code /} or {@code .}
     * @return the report
     * @throws IOException if the tree cannot be read
     */
    public static Report lint(Path root, String groupId, List<String> declared) throws IOException {
        Path real = root.toRealPath();
        List<String> errors = new ArrayList<>();
        List<String> warnings = new ArrayList<>();
        lintRoot(real, errors);
        List<AdocPackages.Package> packages = AdocPackages.packages(real, null);
        for (AdocPackages.Package p : packages) {
            if (!owned(p.name(), groupId, declared)) {
                errors.add("package " + p.name() + " does not begin with the module's group " + groupId
                        + "; move it to a library of its own, or declare the prefix in ike.adoc.packages on purpose");
            }
            for (TopicHeader topic : p.topics()) {
                String domain = TopicRegistry.domainOf(topic.id());
                if (!domain.equals(p.domain())) {
                    errors.add(topic.file() + ": topic " + topic.id() + " is in package " + p.name()
                            + " but its id's domain is " + domain + "; move it to the " + domain
                            + " package or rename it " + p.domain() + "-...");
                }
            }
        }
        for (Path group : AdocPackages.groupDirectories(real)) {
            if (AdocPackages.isDomainPackage(group)) {
                continue;
            }
            Path images = group.resolve(AdocPackages.IMAGES);
            if (Files.isDirectory(images)) {
                errors.add(real.relativize(images).toString().replace('\\', '/')
                        + ": images outside a package; move them into the " + AdocPackages.IMAGES
                        + " directory of the package that uses them");
            }
        }
        for (TopicHeader header : AdocPackages.headers(real, real)) {
            lintAlias(real, header.file(), warnings);
        }
        return new Report(List.copyOf(errors), List.copyOf(warnings));
    }

    /** The root holds nothing but dotted-group directories and META-INF; hidden entries are the editor's. */
    private static void lintRoot(Path real, List<String> errors) throws IOException {
        for (Path entry : AdocPackages.children(real)) {
            String name = entry.getFileName().toString();
            if (name.startsWith(".") || TopicRegistry.SKIPPED_DIRS.contains(name)) {
                continue;
            }
            if (Files.isDirectory(entry)) {
                if (name.equals(AdocPackages.META_INF) || AdocPackages.GROUP.matcher(name).matches()) {
                    continue;
                }
                if (name.equals(AdocPackages.IMAGES)) {
                    errors.add(name + "/: images at the root; move them into the " + AdocPackages.IMAGES
                            + " directory of the package that uses them");
                } else {
                    errors.add(name + "/: not a dotted group directory; the root holds only <group>/<domain>"
                            + " packages and " + AdocPackages.META_INF);
                }
            } else if (name.endsWith(".adoc")) {
                errors.add(name + ": a file at the root; a topic belongs in <group>/<domain>/, the preview"
                        + " index in the library's own package");
            } else {
                errors.add(name + ": a file at the root; the root holds only <group>/<domain> packages and "
                        + AdocPackages.META_INF);
            }
        }
    }

    /**
     * Whether a package passes the ownership rule.
     *
     * @param name     the package name
     * @param groupId  the module's group id
     * @param declared the prefixes {@code ike.adoc.packages} declares
     * @return true when the package begins with the group or a declared prefix
     */
    public static boolean owned(String name, String groupId, List<String> declared) {
        if (begins(name, groupId)) {
            return true;
        }
        for (String prefix : declared) {
            if (begins(name, prefix.strip())) {
                return true;
            }
        }
        return false;
    }

    private static boolean begins(String name, String prefix) {
        return !prefix.isEmpty() && (name.equals(prefix) || name.startsWith(prefix + "/")
                || name.startsWith(prefix + "."));
    }

    /** An include or image line still using the {topics} alias is a warning naming the line. */
    private static void lintAlias(Path real, String file, List<String> warnings) throws IOException {
        List<String> lines = Files.readString(real.resolve(file), StandardCharsets.UTF_8).lines().toList();
        for (int i = 0; i < lines.size(); i++) {
            String line = lines.get(i);
            if (line.startsWith("//") || !line.contains(ALIAS)) {
                continue;
            }
            if (line.startsWith("include::") || line.startsWith("image::") || line.contains("image:")) {
                warnings.add(file + ":" + (i + 1) + ": still uses " + ALIAS + ", replace it with " + ATTRIBUTE
                        + ": " + line.strip());
            }
        }
    }
}