RegistryIndex.java
package network.ike.docs.plugin.diff;
import network.ike.docs.plugin.registry.TopicHeader;
import network.ike.docs.plugin.registry.TopicRegistry;
import java.io.IOException;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* One side's topic registry, generated from the files as they stand on
* that side of a doc-diff comparison: topics grouped by domain (each entry
* in the shape {@code idoc:topic-registry} writes, built from the
* {@code :topic-*:} header), and each assembly's topic membership read
* from its {@code include::} lines. No hand-kept registry file is read.
*
* <p>This is what lets an assembly module's {@code idoc:diff} run
* <em>project</em> the corpus diff onto its own membership
* (ike-issues#649), and what {@link RegistryDelta} compares.
*/
public final class RegistryIndex {
/** An {@code include::} directive's target, up to the attribute list. */
private static final Pattern INCLUDE = Pattern.compile("^include::([^\\[]+)\\[", Pattern.MULTILINE);
/** A leading attribute reference such as {@code {topicsdir}/}. */
private static final Pattern LEADING_ATTRIBUTE = Pattern.compile("^\\{[^}]+\\}/");
private static final String SOURCE_ROOT = "src/docs/asciidoc";
private final Map<String, Map<String, Map<String, Object>>> topicsByDomain;
private final Map<String, String> topicFilesById;
private final Map<String, List<String>> assemblyRefsById;
private RegistryIndex(Map<String, Map<String, Map<String, Object>>> topicsByDomain,
Map<String, String> topicFilesById,
Map<String, List<String>> assemblyRefsById) {
this.topicsByDomain = topicsByDomain;
this.topicFilesById = topicFilesById;
this.assemblyRefsById = assemblyRefsById;
}
/**
* Generate the registry as it stands on one side of a comparison.
*
* @param git repository access
* @param ref the side to read ({@link GitSource#WORKTREE}
* or a committish)
* @param registryRoot repository-relative source root of the topic
* library (the directory holding {@code topics/}),
* or {@code null} when the repository has none
* @return the index (empty when there is no topic library on that side)
* @throws IOException on repository access failure
*/
public static RegistryIndex load(GitSource git, String ref, String registryRoot)
throws IOException {
Map<String, Map<String, Map<String, Object>>> domains = new TreeMap<>();
Map<String, String> files = new LinkedHashMap<>();
Map<String, List<String>> assemblies = new LinkedHashMap<>();
if (registryRoot == null) {
return new RegistryIndex(domains, files, assemblies);
}
String prefix = registryRoot + "/";
for (String path : git.listFiles(ref, registryRoot, ".adoc")) {
String relative = path.substring(prefix.length());
TopicHeader header = TopicHeader.parse(relative, git.read(ref, path));
if (!header.topic()) {
continue;
}
Map<String, Object> entry = TopicRegistry.topicEntry(header, relative);
// Measured on every edit; the packet already shows content changes.
entry.remove("char-count");
domains.computeIfAbsent(TopicRegistry.domainOf(header.id()), k -> new LinkedHashMap<>())
.put(header.id(), entry);
files.put(header.id(), relative);
}
for (String path : git.listFiles(ref, "", ".adoc")) {
if (path.startsWith(prefix)) {
continue;
}
List<String> refs = resolve(includeTargets(git.read(ref, path)), files);
if (!refs.isEmpty()) {
List<String> merged = assemblies.computeIfAbsent(assemblyIdOf(path), k -> new ArrayList<>());
refs.stream().filter(r -> !merged.contains(r)).forEach(merged::add);
}
}
return new RegistryIndex(domains, files, assemblies);
}
/**
* Resolve a topic id to its source file, relative to the registry
* root (e.g. {@code topics/arch/asg-substrate.adoc}).
*
* @param topicId the topic id
* @return the registry-root-relative file, or {@code null} when the
* id is unknown
*/
public String topicFile(String topicId) {
return topicFilesById.get(topicId);
}
/**
* An assembly's topic membership, in include order.
*
* @param assemblyId the assembly id: by IKE naming convention the
* module directory (and artifactId) holding the
* assembly's {@code src/docs/asciidoc}
* @return the topic ids, or {@code null} when no file of that
* assembly includes a topic
*/
public List<String> assemblyRefs(String assemblyId) {
return assemblyRefsById.get(assemblyId);
}
/**
* Topic entries grouped by domain, domains sorted, topics in file order.
*
* @return the entries keyed by domain, then by topic id
*/
Map<String, Map<String, Map<String, Object>>> topicsByDomain() {
return topicsByDomain;
}
/**
* Every assembly's topic membership.
*
* @return topic ids keyed by assembly id
*/
Map<String, List<String>> assemblies() {
return assemblyRefsById;
}
/**
* Render one assembly's membership delta (topics added to and removed
* from its includes between two sides) as a small registry-delta
* partial for an assembly-projection packet.
*
* @param oldIndex the from side
* @param newIndex the to side
* @param fromRef the from-side ref, for the text
* @param toRef the to-side ref (may be {@link GitSource#WORKTREE})
* @param assemblyId the assembly to report on
* @return the partial's text with a level-1 title, or an empty
* string when this assembly's membership is unchanged
*/
public static String membershipDelta(RegistryIndex oldIndex, RegistryIndex newIndex,
String fromRef, String toRef, String assemblyId) {
List<String> oldRefs = oldIndex.assemblyRefsById.getOrDefault(assemblyId, List.of());
List<String> newRefs = newIndex.assemblyRefsById.getOrDefault(assemblyId, List.of());
List<String> plus = newRefs.stream().filter(r -> !oldRefs.contains(r)).toList();
List<String> minus = oldRefs.stream().filter(r -> !newRefs.contains(r)).toList();
if (plus.isEmpty() && minus.isEmpty()) {
return "";
}
StringBuilder sb = new StringBuilder("[[registry-delta]]\n= Membership Delta — ")
.append(assemblyId).append("\n\nTopics included by this assembly changed between ")
.append(fromRef).append(" and ")
.append(GitSource.WORKTREE.equals(toRef) ? "the working tree" : toRef)
.append(".\n\n");
plus.forEach(r -> sb.append("* added `").append(r).append("`\n"));
minus.forEach(r -> sb.append("* removed `").append(r).append("`\n"));
sb.append('\n');
return sb.toString();
}
/**
* The targets of a file's top-level {@code include::} directives, in
* document order, with leading attribute references such as
* {@code {topicsdir}/} and {@code ./} removed.
*
* @param content the file text, possibly {@code null}
* @return the normalized include targets
*/
static List<String> includeTargets(String content) {
List<String> out = new ArrayList<>();
if (content == null) {
return out;
}
Matcher m = INCLUDE.matcher(content);
while (m.find()) {
String target = m.group(1).strip();
String before;
do {
before = target;
target = LEADING_ATTRIBUTE.matcher(target).replaceFirst("");
if (target.startsWith("./")) {
target = target.substring(2);
}
} while (!target.equals(before));
out.add(target);
}
return out;
}
/**
* Map include targets to topic ids by path: a target names a topic
* when it equals the topic's registry-root-relative file or ends with
* it (the assembly reaches the unpacked topic library through an
* attribute such as {@code {topicsdir}}).
*
* @param targets normalized include targets
* @param topicFilesById topic files keyed by id
* @return the topic ids included, in order, without repeats
*/
static List<String> resolve(List<String> targets, Map<String, String> topicFilesById) {
List<String> out = new ArrayList<>();
for (String target : targets) {
for (Map.Entry<String, String> e : topicFilesById.entrySet()) {
String file = e.getValue();
if ((target.equals(file) || target.endsWith("/" + file)) && !out.contains(e.getKey())) {
out.add(e.getKey());
break;
}
}
}
return out;
}
/**
* The assembly id of a file: the module directory that holds its
* {@code src/docs/asciidoc}, or the file's base name for a module at
* the repository root.
*
* @param path repository-relative file path
* @return the assembly id
*/
static String assemblyIdOf(String path) {
int at = path.indexOf("/" + SOURCE_ROOT + "/");
if (at > 0) {
String module = path.substring(0, at);
return module.substring(module.lastIndexOf('/') + 1);
}
String name = path.substring(path.lastIndexOf('/') + 1);
return name.endsWith(".adoc") ? name.substring(0, name.length() - ".adoc".length()) : name;
}
/**
* Find the topic library's source root on a side: the
* {@code …/src/docs/asciidoc} directory whose {@code topics/} holds
* {@code .adoc} files.
*
* @param git repository access
* @param ref the side to search
* @return the repository-relative source root, or {@code null} when
* the repository has no topic library on that side
* @throws IOException on repository access failure
*/
public static String findRoot(GitSource git, String ref) throws IOException {
String marker = SOURCE_ROOT + "/topics/";
for (String path : git.listFiles(ref, "", ".adoc")) {
if (path.startsWith(marker)) {
return SOURCE_ROOT;
}
int at = path.indexOf("/" + marker);
if (at > 0) {
return path.substring(0, at + 1 + SOURCE_ROOT.length());
}
}
return null;
}
}