TopicHeader.java
package network.ike.docs.plugin.registry;
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.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* The parsed header of one AsciiDoc file: the {@code :topic-*:} attribute
* block, the anchor and the level-1 heading, read line by line without
* AsciidoctorJ. The layout is the one {@code IKE-ASCIIDOC-FRAGMENT.md}
* prescribes: an optional comment header, the attribute block (values may
* continue on the next line with a trailing backslash), a literal
* {@code [[anchor]]} equal to the topic id, then {@code = Title}.
*
* <p>A file with no {@code :topic-id:} before its heading is not a topic;
* it is recorded as an assembly (when it carries {@code include::} lines)
* or a plain file, with its title and document attributes, and gets no
* header findings. Every kind of module the doc pipeline renders is
* covered: topic libraries, assemblies, doc-only and hybrid projects.
*
* @param file the file, relative to the scan root, with {@code /} separators
* @param topic whether the file declares a {@code :topic-id:} before its heading
* @param id the topic id, or {@code null} for a file that is not a topic
* @param title the first heading's text: the level-1 heading for a topic;
* for any other file the first heading of any level, so a
* chapter file that starts at {@code ==} still has a title
* @param level the heading level of {@link #title()} (1 for {@code =}),
* or 0 when the file has no heading
* @param attributes every {@code :topic-*:} attribute in declaration order,
* keyed without the {@code topic-} prefix
* @param documentAttributes every other {@code :name: value} attribute in the
* header, before the heading or in the contiguous block
* after it ({@code doctype}, {@code toc}, ...), in order
* @param anchor {@code present}, {@code missing} or {@code mismatched}
* for a topic; {@code null} for other files
* @param charCount characters from the anchor line (or the heading, when
* there is no anchor) to the end of the file
* @param includes the number of {@code include::} lines in the file
* @param findings what is wrong with the header, empty when nothing is
* @since 109
*/
public record TopicHeader(String file, boolean topic, String id, String title, int level,
Map<String, String> attributes, Map<String, String> documentAttributes,
String anchor, long charCount, int includes, List<String> findings) {
/** Attributes every topic must declare, without the {@code topic-} prefix. */
public static final List<String> REQUIRED = List.of("id", "type", "status", "keywords");
/**
* The topic types {@code IKE-TOPIC-REGISTRY.md} allows, plus
* {@code procedure}, which {@code ike-doc-ingest} writes for task topics.
*/
public static final Set<String> TYPES =
Set.of("concept", "task", "procedure", "reference", "dialog");
/** The topic statuses {@code IKE-TOPIC-REGISTRY.md} allows. */
public static final Set<String> STATUSES =
Set.of("draft", "proposed", "review", "published", "deprecated");
/**
* Parse one file.
*
* @param file the file to read, UTF-8
* @param root the scan root the file lies under; {@link #file()} is
* expressed relative to it
* @return the parsed header
* @throws IOException if the file cannot be read
*/
public static TopicHeader parse(Path file, Path root) throws IOException {
String relative = root.relativize(file).toString().replace('\\', '/');
return parse(relative, Files.readString(file, StandardCharsets.UTF_8));
}
/**
* Parse file content already in memory.
*
* @param relative the file's path relative to its scan root
* @param content the file content
* @return the parsed header
*/
public static TopicHeader parse(String relative, String content) {
List<String> lines = content.lines().toList();
Map<String, String> attributes = new LinkedHashMap<>();
Map<String, String> documentAttributes = new LinkedHashMap<>();
String pendingName = null;
StringBuilder pendingValue = null;
String anchorText = null;
int anchorIndex = -1;
int headingIndex = -1;
String title = null;
int level = 0;
for (int i = 0; i < lines.size(); i++) {
String line = lines.get(i);
if (pendingName != null) {
String text = line.strip();
boolean continues = text.endsWith("\\");
String piece = continues ? text.substring(0, text.length() - 1).strip() : text;
if (!piece.isEmpty()) {
pendingValue.append(' ').append(piece);
}
if (!continues) {
attributes.put(pendingName, pendingValue.toString().strip());
pendingName = null;
}
continue;
}
if (line.startsWith("= ")) {
headingIndex = i;
title = line.substring(2).strip();
level = 1;
break;
}
if (line.startsWith("==") && headingIndex < 0 && !attributes.containsKey("id")) {
int depth = 0;
while (depth < line.length() && line.charAt(depth) == '=') {
depth++;
}
if (depth < line.length() && line.charAt(depth) == ' ') {
headingIndex = i;
title = line.substring(depth + 1).strip();
level = depth;
break;
}
}
if (line.startsWith("//")) {
continue;
}
String stripped = line.strip();
if (stripped.startsWith("[[") && stripped.endsWith("]]") && stripped.length() > 4) {
anchorText = stripped.substring(2, stripped.length() - 2).strip();
anchorIndex = i;
continue;
}
if (line.startsWith(":")) {
int close = line.indexOf(':', 1);
if (close > 1) {
String name = line.substring(1, close);
String value = line.substring(close + 1).strip();
if (name.startsWith("topic-")) {
String key = name.substring("topic-".length());
if (value.endsWith("\\")) {
pendingName = key;
pendingValue = new StringBuilder(
value.substring(0, value.length() - 1).strip());
} else {
attributes.put(key, value);
}
} else if (!name.startsWith("!") && !name.endsWith("!")) {
documentAttributes.put(name, value);
}
}
}
}
if (pendingName != null) {
attributes.put(pendingName, pendingValue.toString().strip());
}
// The AsciiDoc document header: attribute lines contiguous with the title.
for (int i = headingIndex + 1; headingIndex >= 0 && i < lines.size(); i++) {
String line = lines.get(i);
if (!line.startsWith(":")) {
break;
}
int close = line.indexOf(':', 1);
if (close > 1) {
String name = line.substring(1, close);
if (!name.startsWith("topic-") && !name.startsWith("!") && !name.endsWith("!")) {
documentAttributes.put(name, line.substring(close + 1).strip());
}
}
}
int includes = 0;
for (String line : lines) {
if (line.startsWith("include::")) {
includes++;
}
}
int start = anchorIndex >= 0 ? anchorIndex : Math.max(headingIndex, 0);
long charCount = 0;
for (int i = start; i < lines.size(); i++) {
charCount += lines.get(i).length() + 1;
}
boolean topic = attributes.containsKey("id");
if (!topic) {
return new TopicHeader(relative, false, null, title, level, attributes,
documentAttributes, null, charCount, includes, List.of());
}
String id = attributes.get("id");
List<String> findings = new ArrayList<>();
List<String> missing = new ArrayList<>();
for (String required : REQUIRED) {
if (!attributes.containsKey(required) || attributes.get(required).isBlank()) {
missing.add(required);
}
}
for (String m : missing) {
findings.add("missing required attribute :topic-" + m + ":");
}
String type = attributes.get("type");
if (type != null && !type.isBlank() && !TYPES.contains(type)) {
findings.add("unknown type '" + type + "' (expected one of " + sorted(TYPES) + ")");
}
String status = attributes.get("status");
if (status != null && !status.isBlank() && !STATUSES.contains(status)) {
findings.add("unknown status '" + status + "' (expected one of " + sorted(STATUSES) + ")");
}
String anchor;
if (anchorText == null) {
anchor = "missing";
findings.add("no [[" + id + "]] anchor before the heading");
} else if (anchorText.equals(id)) {
anchor = "present";
} else {
anchor = "mismatched";
findings.add("anchor [[" + anchorText + "]] does not match :topic-id: " + id);
}
if (headingIndex < 0) {
findings.add("no level-1 heading (= Title)");
}
return new TopicHeader(relative, true, id, title, level, attributes, documentAttributes,
anchor, charCount, includes, List.copyOf(findings));
}
/**
* The required attributes this header lacks, in the order of {@link #REQUIRED}.
*
* @return the missing attribute names without the {@code topic-} prefix
*/
public List<String> missingRequired() {
List<String> missing = new ArrayList<>();
for (String required : REQUIRED) {
if (!attributes.containsKey(required) || attributes.get(required).isBlank()) {
missing.add(required);
}
}
return missing;
}
/**
* The {@code :topic-keywords:} value split on commas and trimmed.
*
* @return the keywords, empty when the attribute is absent
*/
public List<String> keywords() {
String raw = attributes.get("keywords");
if (raw == null || raw.isBlank()) {
return List.of();
}
List<String> out = new ArrayList<>();
for (String k : raw.split(",")) {
String t = k.strip();
if (!t.isEmpty()) {
out.add(t);
}
}
return out;
}
private static List<String> sorted(Set<String> values) {
return values.stream().sorted().toList();
}
}