AdocPackages.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.file.DirectoryStream;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.attribute.BasicFileAttributes;
import java.util.ArrayList;
import java.util.List;
import java.util.TreeMap;
import java.util.regex.Pattern;
/**
* The packages layout of an AsciiDoc root ({@code dev-adoc-packages},
* IKE-Network/ike-issues#1341): the first directory under the root is the
* owning group written as one dotted segment, {@code network.ike.lab}, and
* the directory under that is the topic domain, so a topic is
* {@code network.ike.lab/dev/gitflow-overview.adoc} and its package is
* {@code network.ike.lab/dev}. A library whose group ends in its only
* domain may use the group directory itself as the domain package: the
* ANF kompendium's topics are {@code network.ike.kompendium.anf/determine-topic.adoc},
* in the package {@code network.ike.kompendium.anf}. {@code META-INF} is
* reserved for what describes the artifact; every group begins with a
* top-level domain, so the two never meet.
*
* <p>This class enumerates the packages a root holds and what each holds,
* the reading the manifest and the lint share.
*
* @since 136
*/
public final class AdocPackages {
/** The reserved directory for artifact metadata, never a package. */
public static final String META_INF = "META-INF";
/** The directory inside a package that holds its images. */
public static final String IMAGES = "images";
/**
* A group directory's name: a reverse-DNS group as one dotted segment,
* at least two labels of lowercase letters, digits, hyphens and
* underscores, as a Maven group id is written.
*/
public static final Pattern GROUP = Pattern.compile("[a-z0-9_-]+(\\.[a-z0-9_-]+)+");
/**
* One package of a root.
*
* @param name the package name, {@code <group>/<domain>}, or the
* group alone when the group directory is the domain
* @param domain the topic domain the package's topics must carry as
* the prefix of their id
* @param directory the package directory
* @param kind what the package holds
* @param files every {@code .adoc} file under the package, parsed,
* its path relative to the root, in path order
*/
public record Package(String name, String domain, Path directory, PackageKind kind, List<TopicHeader> files) {
/**
* The files that declare a {@code :topic-id:}.
*
* @return the topics, in path order
*/
public List<TopicHeader> topics() {
return files.stream().filter(TopicHeader::topic).toList();
}
}
private AdocPackages() {
}
/**
* The metadata directory of an artifact inside the zip and the union,
* keyed by its coordinates so that it cannot collide:
* {@code META-INF/ike/<groupId>/<artifactId>}.
*
* @param groupId the artifact's group id
* @param artifactId the artifact's artifact id
* @return the relative path with {@code /} separators
*/
public static String metaDirectory(String groupId, String artifactId) {
return META_INF + "/ike/" + groupId + "/" + artifactId;
}
/**
* The group directories of a root: its immediate subdirectories whose
* name is a dotted group.
*
* @param root the AsciiDoc root
* @return the directories in name order
* @throws IOException if the root cannot be listed
*/
public static List<Path> groupDirectories(Path root) throws IOException {
List<Path> groups = new ArrayList<>();
for (Path entry : children(root)) {
if (Files.isDirectory(entry) && GROUP.matcher(entry.getFileName().toString()).matches()) {
groups.add(entry);
}
}
return groups;
}
/**
* Whether a group directory is itself the domain package: it holds an
* {@code .adoc} file directly, as the ANF library's group directory does.
*
* @param group the group directory
* @return true when the group directory holds topics directly
* @throws IOException if the directory cannot be listed
*/
public static boolean isDomainPackage(Path group) throws IOException {
for (Path entry : children(group)) {
if (Files.isRegularFile(entry) && entry.getFileName().toString().endsWith(".adoc")) {
return true;
}
}
return false;
}
/**
* Enumerate the packages of a root: for each group directory, the group
* itself when it holds topics directly, otherwise each subdirectory of
* it as {@code <group>/<domain>}, hidden directories left out. Every
* {@code .adoc} file under a package is parsed for its header, which
* is what the kind and the lint's domain rule are decided by.
*
* @param root the AsciiDoc root
* @param libraryPackage the package {@code ike.adoc.library-package}
* names as the library's own, or {@code null}
* @return the packages in name order
* @throws IOException if the tree cannot be read
*/
public static List<Package> packages(Path root, String libraryPackage) throws IOException {
Path real = root.toRealPath();
TreeMap<String, Package> packages = new TreeMap<>();
for (Path group : groupDirectories(real)) {
String groupName = group.getFileName().toString();
if (isDomainPackage(group)) {
String domain = groupName.substring(groupName.lastIndexOf('.') + 1);
packages.put(groupName, read(real, groupName, domain, group, libraryPackage));
continue;
}
for (Path domainDir : children(group)) {
String domain = domainDir.getFileName().toString();
if (!Files.isDirectory(domainDir) || domain.startsWith(".")) {
continue;
}
String name = groupName + "/" + domain;
packages.put(name, read(real, name, domain, domainDir, libraryPackage));
}
}
return List.copyOf(packages.values());
}
private static Package read(Path real, String name, String domain, Path directory, String libraryPackage)
throws IOException {
List<TopicHeader> files = headers(real, directory);
boolean index = Files.isRegularFile(directory.resolve("index.adoc"));
boolean topics = files.stream().anyMatch(TopicHeader::topic);
PackageKind kind = name.equals(libraryPackage) || (index && !topics)
? PackageKind.LIBRARY : PackageKind.TOPICS;
return new Package(name, domain, directory, kind, files);
}
/**
* Parse the header of every {@code .adoc} file under a directory, in
* path order, paths relative to the root; symbolic links and the
* directories {@link TopicRegistry#SKIPPED_DIRS} are left out.
*
* @param root the AsciiDoc root paths are relative to
* @param directory the directory to walk, under the root
* @return the parsed headers
* @throws IOException if a file cannot be read
*/
public static List<TopicHeader> headers(Path root, Path directory) throws IOException {
List<Path> files = new ArrayList<>();
Files.walkFileTree(directory, new SimpleFileVisitor<>() {
@Override
public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) {
if (!dir.equals(directory) && TopicRegistry.SKIPPED_DIRS.contains(dir.getFileName().toString())) {
return FileVisitResult.SKIP_SUBTREE;
}
return FileVisitResult.CONTINUE;
}
@Override
public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
if (attrs.isRegularFile() && !attrs.isSymbolicLink()
&& file.getFileName().toString().endsWith(".adoc")) {
files.add(file);
}
return FileVisitResult.CONTINUE;
}
});
files.sort((a, b) -> root.relativize(a).toString().compareTo(root.relativize(b).toString()));
List<TopicHeader> headers = new ArrayList<>();
for (Path file : files) {
headers.add(TopicHeader.parse(file, root));
}
return List.copyOf(headers);
}
/**
* The immediate entries of a directory in name order.
*
* @param directory the directory
* @return its entries
* @throws IOException if it cannot be listed
*/
public static List<Path> children(Path directory) throws IOException {
List<Path> entries = new ArrayList<>();
try (DirectoryStream<Path> stream = Files.newDirectoryStream(directory)) {
for (Path entry : stream) {
entries.add(entry);
}
}
entries.sort((a, b) -> a.getFileName().toString().compareTo(b.getFileName().toString()));
return entries;
}
}