TopicRegistry.java

package network.ike.docs.plugin.registry;

import network.ike.docs.plugin.diff.PacketAssembler;
import org.yaml.snakeyaml.LoaderOptions;
import org.yaml.snakeyaml.Yaml;
import org.yaml.snakeyaml.constructor.SafeConstructor;

import java.io.File;
import java.io.IOException;
import java.io.Reader;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
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.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.TreeMap;

/**
 * The generated topic registry: every AsciiDoc file under a scan root, parsed
 * by {@link TopicHeader}, in the shape {@code IKE-TOPIC-REGISTRY.md} gives
 * {@code topic-registry.yaml}: topics grouped into domains by the prefix of
 * their id, each with the registry's field names ({@code id}, {@code file},
 * {@code title}, {@code type}, {@code keywords}, {@code status},
 * {@code char-count}, {@code related}, {@code summary}), then what a build can
 * add on top: assemblies and plain files with their document attributes, the
 * findings the headers raise, and a generation stamp. This is the registry's
 * build-time revision: generated from the files on every run where, before it,
 * the same registry was kept by hand at {@code src/docs/asciidoc/topic-registry.yaml}.
 * Pure Java with no Maven dependency, so it is testable without a build;
 * {@code TopicRegistryMojo} is the wiring around it.
 *
 * @since 109
 */
public final class TopicRegistry {

    /** Directory names never entered by the scan. */
    public static final Set<String> SKIPPED_DIRS = Set.of("target", ".git", "node_modules");

    /**
     * One scan root's result.
     *
     * @param root     the root that was scanned
     * @param topics   the files that declare a {@code :topic-id:}, in path order
     * @param others   the files that do not, in path order
     * @param findings every finding, each prefixed with the file it concerns
     */
    public record Scan(Path root, List<TopicHeader> topics, List<TopicHeader> others,
                       List<String> findings) {
    }

    private TopicRegistry() {
    }

    /**
     * Scan one root.
     *
     * @param root     the directory to scan
     * @param maxFiles the most {@code .adoc} files the scan will accept
     * @return the scan result
     * @throws IOException           if the tree cannot be read
     * @throws IllegalStateException if the root holds more than {@code maxFiles}
     *                               {@code .adoc} files
     */
    public static Scan scan(Path root, int maxFiles) throws IOException {
        Path real = root.toRealPath();
        List<Path> files = new ArrayList<>();
        List<String> linkFindings = new ArrayList<>();
        // Links are never followed, so containment holds without resolving each
        // file's real path (which cost as much as parsing); a linked .adoc is
        // reported and skipped instead.
        Files.walkFileTree(real, new SimpleFileVisitor<>() {
            @Override
            public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) {
                if (!dir.equals(real) && SKIPPED_DIRS.contains(dir.getFileName().toString())) {
                    return FileVisitResult.SKIP_SUBTREE;
                }
                return FileVisitResult.CONTINUE;
            }

            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
                if (!file.getFileName().toString().endsWith(".adoc")) {
                    return FileVisitResult.CONTINUE;
                }
                if (attrs.isSymbolicLink()) {
                    linkFindings.add(real.relativize(file).toString().replace('\\', '/')
                            + ": symbolic link, skipped");
                } else if (attrs.isRegularFile()) {
                    files.add(file);
                }
                return FileVisitResult.CONTINUE;
            }
        });
        if (files.size() > maxFiles) {
            throw new IllegalStateException("More than " + maxFiles + " .adoc files under "
                    + real + "; raise -Dike.topic-registry.maxFiles or narrow -Dike.topic-registry.roots");
        }
        files.sort((a, b) -> real.relativize(a).toString().compareTo(real.relativize(b).toString()));

        // Parse in parallel; toList() keeps the sorted encounter order.
        List<TopicHeader> headers;
        try {
            headers = files.parallelStream().map(file -> {
                try {
                    return TopicHeader.parse(file, real);
                } catch (IOException e) {
                    throw new UncheckedIOException(e);
                }
            }).toList();
        } catch (UncheckedIOException e) {
            throw e.getCause();
        }
        return collect(real, headers, linkFindings);
    }

    /**
     * Scan from one root file: the file and every {@code .adoc} file it
     * reaches through {@code include::} lines, followed recursively and
     * resolved relative to the including file as the AsciiDoc preprocessor
     * does. Files under the root that are not reached are left out. An
     * include whose target cannot be resolved statically (an attribute
     * reference, an absolute path, a URI, a path above the root) or that
     * names a missing file is a finding; a target that is not an
     * {@code .adoc} file (a diagram, a CSV) is passed over. Each file is read
     * once, so an include cycle ends.
     *
     * @param root     the scan root; registry paths are relative to it
     * @param rootFile the {@code .adoc} file to start from, under {@code root}
     * @return the scan result
     * @throws IOException              if a file cannot be read
     * @throws IllegalArgumentException if {@code rootFile} is not an
     *                                  {@code .adoc} file under {@code root}
     */
    public static Scan scanFrom(Path root, Path rootFile) throws IOException {
        Path real = root.toRealPath();
        if (!Files.isRegularFile(rootFile) || !rootFile.getFileName().toString().endsWith(".adoc")) {
            throw new IllegalArgumentException("Not an AsciiDoc file: " + rootFile);
        }
        Path start = rootFile.toRealPath();
        if (!start.startsWith(real)) {
            throw new IllegalArgumentException(rootFile + " is not under the registry root " + real);
        }
        String first = real.relativize(start).toString().replace(File.separatorChar, '/');
        Set<String> seen = new HashSet<>(List.of(first));
        Deque<String> queue = new ArrayDeque<>(List.of(first));
        List<TopicHeader> headers = new ArrayList<>();
        List<String> includeFindings = new ArrayList<>();
        while (!queue.isEmpty()) {
            String relative = queue.removeFirst();
            String content = Files.readString(real.resolve(relative), StandardCharsets.UTF_8);
            headers.add(TopicHeader.parse(relative, content));
            for (String line : content.lines().toList()) {
                int bracket = line.indexOf('[');
                if (!line.startsWith("include::") || bracket < 0) {
                    continue;
                }
                String target = line.substring("include::".length(), bracket).strip();
                String resolved = PacketAssembler.resolveInclude(relative, target);
                if (resolved == null) {
                    includeFindings.add(relative + ": include::" + target
                            + "[] not followed (attribute reference, absolute path, URI or above the root)");
                    continue;
                }
                if (!resolved.endsWith(".adoc") || !seen.add(resolved)) {
                    continue;
                }
                Path file = real.resolve(resolved);
                if (Files.isSymbolicLink(file)) {
                    includeFindings.add(resolved + ": symbolic link, skipped");
                } else if (!Files.isRegularFile(file)) {
                    includeFindings.add(relative + ": include::" + target + "[] does not resolve to a file");
                } else {
                    queue.addLast(resolved);
                }
            }
        }
        headers.sort((a, b) -> a.file().compareTo(b.file()));
        return collect(real, headers, includeFindings);
    }

    /**
     * Group parsed headers into topics and other files and gather their
     * findings, the part of a scan shared by {@link #scan} and
     * {@link #scanFrom}.
     */
    private static Scan collect(Path real, List<TopicHeader> headers, List<String> earlyFindings) {
        List<TopicHeader> topics = new ArrayList<>();
        List<TopicHeader> others = new ArrayList<>();
        List<String> findings = new ArrayList<>(earlyFindings);
        findings.sort(null);
        Map<String, String> firstFileById = new LinkedHashMap<>();
        for (TopicHeader header : headers) {
            String relative = header.file();
            if (header.topic()) {
                topics.add(header);
                String earlier = firstFileById.putIfAbsent(header.id(), relative);
                if (earlier != null) {
                    findings.add(relative + ": duplicate id '" + header.id()
                            + "', already declared by " + earlier);
                }
            } else {
                others.add(header);
            }
            for (String f : header.findings()) {
                findings.add(relative + ": " + f);
            }
        }
        return new Scan(real, List.copyOf(topics), List.copyOf(others), List.copyOf(findings));
    }

    /**
     * The domain a topic belongs to: the part of its id before the first
     * hyphen, the {@code {domain-prefix}-{slug}} rule of
     * {@code IKE-TOPIC-REGISTRY.md}.
     *
     * @param id the topic id
     * @return the domain id, or the whole id when it has no hyphen
     */
    public static String domainOf(String id) {
        int i = id.indexOf('-');
        return i <= 0 ? id : id.substring(0, i);
    }

    /**
     * The registry as an ordered map, ready for YAML: the schema's keys first
     * ({@code registry-version}, {@code generated}, {@code topic-count},
     * {@code domains} with their {@code topics}), then {@code assemblies},
     * {@code other-files} and {@code findings}. Topics are grouped by
     * {@link #domainOf domain} and sorted by id. A file path is relative to
     * its root, prefixed with the root when several roots were scanned.
     *
     * @param scans the scanned roots
     * @param base  the directory root paths are made relative to (the module
     *              base directory)
     * @param now   the generation instant
     * @return the registry model
     */
    public static Map<String, Object> model(List<Scan> scans, Path base, Instant now) {
        Map<String, Object> registry = new LinkedHashMap<>();
        registry.put("registry-version", "1.2");
        registry.put("generated", now.truncatedTo(ChronoUnit.SECONDS).toString());
        registry.put("scanned-from", base.toAbsolutePath().normalize().toString());
        List<String> roots = new ArrayList<>();
        for (Scan scan : scans) {
            roots.add(relativeTo(base, scan.root()));
        }
        registry.put("roots", roots);
        boolean prefix = scans.size() > 1;
        TreeMap<String, List<Map<String, Object>>> domains = new TreeMap<>();
        List<Object> assemblies = new ArrayList<>();
        List<Object> otherFiles = new ArrayList<>();
        List<String> findings = new ArrayList<>();
        int files = 0;
        int topics = 0;
        for (int i = 0; i < scans.size(); i++) {
            Scan scan = scans.get(i);
            String rootPrefix = prefix ? roots.get(i) + "/" : "";
            files += scan.topics().size() + scan.others().size();
            topics += scan.topics().size();
            for (TopicHeader t : scan.topics()) {
                domains.computeIfAbsent(domainOf(t.id()), k -> new ArrayList<>())
                        .add(topicEntry(t, rootPrefix + t.file()));
            }
            for (TopicHeader o : scan.others()) {
                (o.includes() > 0 ? assemblies : otherFiles).add(otherEntry(o, rootPrefix + o.file()));
            }
            for (String f : scan.findings()) {
                findings.add(rootPrefix + f);
            }
        }
        registry.put("topic-count", topics);
        registry.put("file-count", files);
        List<Object> domainList = new ArrayList<>();
        for (Map.Entry<String, List<Map<String, Object>>> e : domains.entrySet()) {
            Map<String, Object> domain = new LinkedHashMap<>();
            domain.put("id", e.getKey());
            e.getValue().sort((x, y) -> String.valueOf(x.get("id")).compareTo(String.valueOf(y.get("id"))));
            domain.put("topics", e.getValue());
            domainList.add(domain);
        }
        registry.put("domains", domainList);
        registry.put("assemblies", assemblies);
        registry.put("other-files", otherFiles);
        registry.put("findings", findings);
        return registry;
    }

    /**
     * Render the registry model as YAML in the registry's block style: two-space
     * indent, sequences indented under their key, one scalar per line. Written
     * directly rather than through SnakeYAML's emitter, which cost 40 percent
     * of a large run and about 45 ms of class loading on every small one; the
     * output round-trips through {@link #load} unchanged.
     *
     * @param model the registry model from {@link #model}
     * @return the YAML text
     */
    public static String yaml(Map<String, Object> model) {
        return yaml(model, "topic-registry.yaml, generated by idoc:topic-registry from the files. Do not edit.");
    }

    /**
     * Render a model as YAML in the registry's block style under a given
     * header comment, the shape shared by the registry, the term index and
     * the package manifest.
     *
     * @param model   the model, an ordered map of scalars, lists and maps
     * @param comment the header comment, without the leading {@code #}
     * @return the YAML text
     */
    public static String yaml(Map<String, Object> model, String comment) {
        StringBuilder sb = new StringBuilder(1 << 16);
        sb.append("# ").append(comment).append('\n');
        emitMap(sb, model, 0);
        return sb.toString();
    }

    private static void emitMap(StringBuilder sb, Map<?, ?> map, int indent) {
        for (Map.Entry<?, ?> e : map.entrySet()) {
            pad(sb, indent).append(scalar(String.valueOf(e.getKey()))).append(':');
            emitValue(sb, e.getValue(), indent);
        }
    }

    private static void emitValue(StringBuilder sb, Object value, int indent) {
        if (value instanceof Map<?, ?> m) {
            if (m.isEmpty()) {
                sb.append(" {}\n");
            } else {
                sb.append('\n');
                emitMap(sb, m, indent + 2);
            }
        } else if (value instanceof List<?> l) {
            if (l.isEmpty()) {
                sb.append(" []\n");
                return;
            }
            sb.append('\n');
            for (Object item : l) {
                pad(sb, indent + 2).append('-');
                if (item instanceof Map<?, ?> m && !m.isEmpty()) {
                    boolean first = true;
                    for (Map.Entry<?, ?> e : m.entrySet()) {
                        if (first) {
                            sb.append(' ');
                            first = false;
                        } else {
                            pad(sb, indent + 4);
                        }
                        sb.append(scalar(String.valueOf(e.getKey()))).append(':');
                        emitValue(sb, e.getValue(), indent + 4);
                    }
                } else {
                    sb.append(' ');
                    emitScalarOrEmpty(sb, item);
                    sb.append('\n');
                }
            }
        } else {
            sb.append(' ');
            emitScalarOrEmpty(sb, value);
            sb.append('\n');
        }
    }

    private static void emitScalarOrEmpty(StringBuilder sb, Object value) {
        if (value instanceof Map<?, ?>) {
            sb.append("{}");
        } else if (value instanceof List<?>) {
            sb.append("[]");
        } else {
            sb.append(scalar(value));
        }
    }

    /** Words YAML 1.1 reads as booleans or null when unquoted. */
    private static final Set<String> RESERVED = Set.of("true", "false", "yes", "no", "on", "off",
            "y", "n", "null", "~", ".inf", "-.inf", ".nan");

    /**
     * A scalar as YAML: numbers and booleans plain; strings plain when SnakeYAML
     * would read them back as the same string, otherwise single-quoted (or
     * double-quoted when they hold control characters).
     */
    static String scalar(Object value) {
        if (value == null) {
            return "null";
        }
        if (value instanceof Number || value instanceof Boolean) {
            return String.valueOf(value);
        }
        String s = String.valueOf(value);
        if (s.isEmpty()) {
            return "''";
        }
        boolean control = false;
        for (int i = 0; i < s.length(); i++) {
            char c = s.charAt(i);
            if (c < 0x20 || c == 0x7f) {
                control = true;
                break;
            }
        }
        if (control) {
            StringBuilder sb = new StringBuilder("\"");
            for (int i = 0; i < s.length(); i++) {
                char c = s.charAt(i);
                switch (c) {
                    case '"' -> sb.append("\\\"");
                    case '\\' -> sb.append("\\\\");
                    case '\n' -> sb.append("\\n");
                    case '\t' -> sb.append("\\t");
                    case '\r' -> sb.append("\\r");
                    default -> {
                        if (c < 0x20 || c == 0x7f) {
                            sb.append(String.format("\\x%02x", (int) c));
                        } else {
                            sb.append(c);
                        }
                    }
                }
            }
            return sb.append('"').toString();
        }
        if (isPlain(s)) {
            return s;
        }
        return "'" + s.replace("'", "''") + "'";
    }

    private static boolean isPlain(String s) {
        char first = s.charAt(0);
        char last = s.charAt(s.length() - 1);
        if (first == ' ' || last == ' ' || last == ':') {
            return false;
        }
        if ("-?:,[]{}#&*!|>'\"%@`".indexOf(first) >= 0) {
            return false;
        }
        if (s.contains(": ") || s.contains(" #") || s.contains("\t")) {
            return false;
        }
        if (RESERVED.contains(s.toLowerCase(java.util.Locale.ROOT))) {
            return false;
        }
        // Anything SnakeYAML could take for a number, a timestamp or a sexagesimal;
        // only strings that start like one need the regex.
        if ((Character.isDigit(first) || first == '.' || first == '+') && LOOKS_TYPED.matcher(s).matches()) {
            return false;
        }
        return true;
    }

    private static final java.util.regex.Pattern LOOKS_TYPED = java.util.regex.Pattern.compile(
            "[-+]?(\\d[\\d_]*)?(\\.\\d[\\d_]*)?([eE][-+]?\\d+)?|0x[0-9a-fA-F_]+|0o?[0-7_]+|0b[01_]+"
                    + "|[-+]?\\d[\\d_]*(:[0-5]?\\d)+(\\.\\d+)?|\\d{4}-\\d\\d?-\\d\\d?([Tt ].*)?");

    private static StringBuilder pad(StringBuilder sb, int n) {
        for (int i = 0; i < n; i++) {
            sb.append(' ');
        }
        return sb;
    }

    /**
     * The scan as an indented tree for the build log: directories, then
     * each file with its id, type and status, and the files that are not
     * topics with their include counts.
     *
     * @param scan the scan
     * @param base the directory the root is shown relative to
     * @return the lines, without newlines
     */
    public static List<String> tree(Scan scan, Path base) {
        List<String> lines = new ArrayList<>();
        lines.add(relativeTo(base, scan.root()));
        Map<String, List<TopicHeader>> byDir = new TreeMap<>();
        for (TopicHeader t : scan.topics()) {
            byDir.computeIfAbsent(directoryOf(t.file()), k -> new ArrayList<>()).add(t);
        }
        for (TopicHeader o : scan.others()) {
            byDir.computeIfAbsent(directoryOf(o.file()), k -> new ArrayList<>()).add(o);
        }
        for (Map.Entry<String, List<TopicHeader>> e : byDir.entrySet()) {
            String indent = "  ";
            if (!e.getKey().isEmpty()) {
                lines.add("  " + e.getKey() + "/");
                indent = "    ";
            }
            for (TopicHeader h : e.getValue()) {
                String name = h.file().substring(h.file().lastIndexOf('/') + 1);
                if (h.topic()) {
                    lines.add(indent + pad(name, 40) + pad(h.id(), 38)
                            + pad(h.attributes().getOrDefault("type", "-"), 11)
                            + h.attributes().getOrDefault("status", "-"));
                } else {
                    lines.add(indent + pad(name, 40)
                            + (h.includes() > 0 ? "assembly, " + h.includes() + " includes" : "plain"));
                }
            }
        }
        return lines;
    }

    /**
     * Read a registry written by {@link #yaml(Map)} back into its model.
     *
     * @param registryFile the generated registry file
     * @return the model, with the same shape {@link #model} produces
     * @throws IOException if the file cannot be read or is not a generated registry
     */
    public static Map<String, Object> load(Path registryFile) throws IOException {
        LoaderOptions options = new LoaderOptions();
        // SnakeYAML refuses documents over 3 MB by default; a registry of a few
        // thousand topics is larger than that. 256 MB is far above any corpus.
        options.setCodePointLimit(256 * 1024 * 1024);
        Yaml yaml = new Yaml(new SafeConstructor(options));
        try (Reader reader = Files.newBufferedReader(registryFile, StandardCharsets.UTF_8)) {
            Object loaded = yaml.load(reader);
            if (!(loaded instanceof Map<?, ?> map) || !(map.get("domains") instanceof List<?>)
                    || !(map.get("roots") instanceof List<?>)) {
                throw new IOException("Not a generated topic registry: " + registryFile);
            }
            @SuppressWarnings("unchecked")
            Map<String, Object> model = (Map<String, Object>) map;
            return model;
        }
    }

    /**
     * Add files to an existing registry, or refresh their entries, without
     * rescanning the roots: each file is parsed alone, placed in its domain in
     * id order, counted, and checked for a duplicate id against the ids the
     * registry already holds. An entry for the same file is replaced, so a
     * re-ingested document is safe to add again. Files the registry lists but
     * that no longer exist are not noticed here; a full scan is.
     *
     * @param model the registry model, from {@link #model} or {@link #load};
     *              updated in place
     * @param base  the module base directory the registry's roots are relative to
     * @param files the files to add, relative to {@code base} or absolute; each
     *              must be an {@code .adoc} file under one of the registry's roots
     * @param now   the update instant, recorded as {@code generated}
     * @return the parsed headers of the added files, in the order given
     * @throws IOException              if a file cannot be read
     * @throws IllegalArgumentException if a file is missing, is not AsciiDoc,
     *                                  or lies under none of the registry's roots
     */
    @SuppressWarnings("unchecked")
    public static List<TopicHeader> add(Map<String, Object> model, Path base, List<Path> files,
                                        Instant now) throws IOException {
        List<String> roots = new ArrayList<>();
        for (Object r : (List<Object>) model.get("roots")) {
            roots.add(String.valueOf(r));
        }
        boolean prefix = roots.size() > 1;
        List<String> findings = new ArrayList<>();
        for (Object f : (List<Object>) model.getOrDefault("findings", List.of())) {
            findings.add(String.valueOf(f));
        }
        List<TopicHeader> added = new ArrayList<>();
        for (Path file : files) {
            Path abs = base.resolve(file);
            if (!Files.isRegularFile(abs)) {
                throw new IllegalArgumentException("Not a file: " + abs);
            }
            if (!abs.getFileName().toString().endsWith(".adoc")) {
                throw new IllegalArgumentException("Not an AsciiDoc file: " + abs);
            }
            Path real = abs.toRealPath();
            String rootName = null;
            Path rootPath = null;
            for (String name : roots) {
                Path candidate = base.resolve(name);
                if (Files.isDirectory(candidate) && real.startsWith(candidate.toRealPath())) {
                    rootName = name;
                    rootPath = candidate.toRealPath();
                    break;
                }
            }
            if (rootName == null) {
                throw new IllegalArgumentException(abs + " is under none of the registry's roots "
                        + roots + "; run a full idoc:topic-registry instead");
            }
            TopicHeader header = TopicHeader.parse(real, rootPath);
            String fileValue = (prefix ? rootName + "/" : "") + header.file();
            remove(model, fileValue);
            findings.removeIf(f -> f.startsWith(fileValue + ": "));
            if (header.topic()) {
                String earlier = fileDeclaring(model, header.id());
                if (earlier != null) {
                    findings.add(fileValue + ": duplicate id '" + header.id()
                            + "', already declared by " + earlier);
                }
                insertTopic(model, header, fileValue);
            } else {
                insertOther(model, header, fileValue);
            }
            for (String f : header.findings()) {
                findings.add(fileValue + ": " + f);
            }
            added.add(header);
        }
        recount(model);
        model.put("generated", now.truncatedTo(ChronoUnit.SECONDS).toString());
        model.put("findings", findings);
        return added;
    }

    @SuppressWarnings("unchecked")
    private static List<Map<String, Object>> listOf(Map<String, Object> holder, String key) {
        return (List<Map<String, Object>>) holder.computeIfAbsent(key, k -> new ArrayList<>());
    }

    private static void remove(Map<String, Object> model, String fileValue) {
        for (Iterator<Map<String, Object>> it = listOf(model, "domains").iterator(); it.hasNext();) {
            Map<String, Object> domain = it.next();
            List<Map<String, Object>> topics = listOf(domain, "topics");
            topics.removeIf(t -> fileValue.equals(t.get("file")));
            if (topics.isEmpty()) {
                it.remove();
            }
        }
        listOf(model, "assemblies").removeIf(o -> fileValue.equals(o.get("file")));
        listOf(model, "other-files").removeIf(o -> fileValue.equals(o.get("file")));
    }

    private static String fileDeclaring(Map<String, Object> model, String id) {
        for (Map<String, Object> domain : listOf(model, "domains")) {
            for (Map<String, Object> t : listOf(domain, "topics")) {
                if (id.equals(t.get("id"))) {
                    return String.valueOf(t.get("file"));
                }
            }
        }
        return null;
    }

    private static void insertTopic(Map<String, Object> model, TopicHeader header, String fileValue) {
        List<Map<String, Object>> domains = listOf(model, "domains");
        String key = domainOf(header.id());
        Map<String, Object> domain = null;
        int position = 0;
        for (int i = 0; i < domains.size(); i++) {
            String d = String.valueOf(domains.get(i).get("id"));
            if (d.equals(key)) {
                domain = domains.get(i);
                break;
            }
            if (d.compareTo(key) < 0) {
                position = i + 1;
            }
        }
        if (domain == null) {
            domain = new LinkedHashMap<>();
            domain.put("id", key);
            domain.put("topics", new ArrayList<>());
            domains.add(position, domain);
        }
        List<Map<String, Object>> topics = listOf(domain, "topics");
        int at = 0;
        while (at < topics.size()
                && String.valueOf(topics.get(at).get("id")).compareTo(header.id()) <= 0) {
            at++;
        }
        topics.add(at, topicEntry(header, fileValue));
    }

    private static void insertOther(Map<String, Object> model, TopicHeader header, String fileValue) {
        List<Map<String, Object>> list = listOf(model, header.includes() > 0 ? "assemblies" : "other-files");
        int at = 0;
        while (at < list.size()
                && String.valueOf(list.get(at).get("file")).compareTo(fileValue) < 0) {
            at++;
        }
        list.add(at, otherEntry(header, fileValue));
    }

    private static void recount(Map<String, Object> model) {
        int topics = 0;
        for (Map<String, Object> domain : listOf(model, "domains")) {
            topics += listOf(domain, "topics").size();
        }
        model.put("topic-count", topics);
        model.put("file-count", topics + listOf(model, "assemblies").size()
                + listOf(model, "other-files").size());
    }

    /**
     * An assembly or plain file: its path, title, document attributes and
     * include count.
     *
     * @param o         the parsed header of a file that is not a topic
     * @param fileValue the file path to record
     * @return the registry entry
     */
    public static Map<String, Object> otherEntry(TopicHeader o, String fileValue) {
        Map<String, Object> entry = new LinkedHashMap<>();
        entry.put("file", fileValue);
        if (o.title() != null) {
            entry.put("title", o.title());
            if (o.level() != 1) {
                entry.put("level", o.level());
            }
        }
        if (!o.documentAttributes().isEmpty()) {
            entry.put("attributes", new LinkedHashMap<>(o.documentAttributes()));
        }
        if (o.includes() > 0) {
            entry.put("includes", o.includes());
        }
        return entry;
    }

    /**
     * One topic in the registry's field order ({@code id}, {@code file},
     * {@code title}, {@code type}, {@code keywords}, {@code status},
     * {@code char-count}, {@code dependencies}, {@code related},
     * {@code summary}, {@code supersedes}, {@code notes}), then what the
     * header adds: provenance, scope note, citation, license, the anchor and
     * header verdicts, unknown {@code :topic-*:} attributes under
     * {@code extra}, document attributes, and the include count.
     * Shared with {@code idoc:diff}, which generates the registry for each
     * side of a comparison in this same shape.
     *
     * @param t         the parsed topic header
     * @param fileValue the file path to record
     * @return the registry entry
     */
    public static Map<String, Object> topicEntry(TopicHeader t, String fileValue) {
        Map<String, Object> entry = new LinkedHashMap<>();
        entry.put("id", t.id());
        entry.put("file", fileValue);
        if (t.title() != null) {
            entry.put("title", t.title());
        }
        putIfPresent(entry, "type", t.attributes().get("type"));
        entry.put("keywords", t.keywords());
        putIfPresent(entry, "status", t.attributes().get("status"));
        entry.put("char-count", t.charCount());
        putListIfPresent(entry, "dependencies", t.attributes().get("dependencies"));
        putListIfPresent(entry, "related", t.attributes().get("related"));
        putIfPresent(entry, "summary", t.attributes().get("summary"));
        putIfPresent(entry, "supersedes", t.attributes().get("supersedes"));
        putIfPresent(entry, "notes", t.attributes().get("notes"));
        putIfPresent(entry, "provenance", t.attributes().get("provenance"));
        putIfPresent(entry, "scope-note", t.attributes().get("scope-note"));
        putIfPresent(entry, "citation", t.attributes().get("citation"));
        putIfPresent(entry, "license", t.attributes().get("license"));
        entry.put("anchor", t.anchor());
        List<String> missing = t.missingRequired();
        entry.put("header", missing.isEmpty() ? "complete" : "missing: " + String.join(", ", missing));
        Map<String, String> extra = new LinkedHashMap<>();
        Set<String> known = Set.of("id", "type", "keywords", "status", "dependencies", "related",
                "summary", "supersedes", "notes", "provenance", "scope-note", "citation", "license");
        for (Map.Entry<String, String> a : t.attributes().entrySet()) {
            if (!known.contains(a.getKey())) {
                extra.put(a.getKey(), a.getValue());
            }
        }
        if (!extra.isEmpty()) {
            entry.put("extra", extra);
        }
        if (!t.documentAttributes().isEmpty()) {
            entry.put("attributes", new LinkedHashMap<>(t.documentAttributes()));
        }
        if (t.includes() > 0) {
            entry.put("includes", t.includes());
        }
        return entry;
    }

    private static void putIfPresent(Map<String, Object> entry, String key, String value) {
        if (value != null && !value.isBlank()) {
            entry.put(key, value);
        }
    }

    private static void putListIfPresent(Map<String, Object> entry, String key, String value) {
        if (value != null && !value.isBlank()) {
            entry.put(key, split(value));
        }
    }

    private static List<String> split(String value) {
        List<String> out = new ArrayList<>();
        for (String v : value.split(",")) {
            String t = v.strip();
            if (!t.isEmpty()) {
                out.add(t);
            }
        }
        return out;
    }

    private static String directoryOf(String relativeFile) {
        int slash = relativeFile.lastIndexOf('/');
        return slash < 0 ? "" : relativeFile.substring(0, slash);
    }

    private static String relativeTo(Path base, Path path) {
        try {
            Path b = base.toRealPath();
            if (path.startsWith(b)) {
                String relative = b.relativize(path).toString().replace('\\', '/');
                return relative.isEmpty() ? "." : relative;
            }
        } catch (IOException e) {
            // fall through to the absolute form
        }
        return path.toString();
    }

    private static String pad(String s, int width) {
        return s.length() >= width ? s + " " : s + " ".repeat(width - s.length());
    }
}