Class TopicRegistry

java.lang.Object
network.ike.docs.plugin.registry.TopicRegistry

public final class TopicRegistry extends Object
The generated topic registry: every AsciiDoc file under a scan root, parsed by TopicHeader, in the shape IKE-TOPIC-REGISTRY.md gives topic-registry.yaml: topics grouped into domains by the prefix of their id, each with the registry's field names (id, file, title, type, keywords, status, char-count, related, 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 src/docs/asciidoc/topic-registry.yaml. Pure Java with no Maven dependency, so it is testable without a build; TopicRegistryMojo is the wiring around it.
Since:
109
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    One scan root's result.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Set<String>
    Directory names never entered by the scan.
  • Method Summary

    Modifier and Type
    Method
    Description
    add(Map<String,Object> model, Path base, List<Path> files, Instant now)
    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.
    static String
    The domain a topic belongs to: the part of its id before the first hyphen, the {domain-prefix}-{slug} rule of IKE-TOPIC-REGISTRY.md.
    static Map<String,Object>
    load(Path registryFile)
    Read a registry written by yaml(Map) back into its model.
    static Map<String,Object>
    model(List<TopicRegistry.Scan> scans, Path base, Instant now)
    The registry as an ordered map, ready for YAML: the schema's keys first (registry-version, generated, topic-count, domains with their topics), then assemblies, other-files and findings.
    static Map<String,Object>
    otherEntry(TopicHeader o, String fileValue)
    An assembly or plain file: its path, title, document attributes and include count.
    scan(Path root, int maxFiles)
    Scan one root.
    scanFrom(Path root, Path rootFile)
    Scan from one root file: the file and every .adoc file it reaches through include:: lines, followed recursively and resolved relative to the including file as the AsciiDoc preprocessor does.
    static Map<String,Object>
    topicEntry(TopicHeader t, String fileValue)
    One topic in the registry's field order (id, file, title, type, keywords, status, char-count, dependencies, related, summary, supersedes, notes), then what the header adds: provenance, scope note, citation, license, the anchor and header verdicts, unknown :topic-*: attributes under extra, document attributes, and the include count.
    static List<String>
    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.
    static String
    Render the registry model as YAML in the registry's block style: two-space indent, sequences indented under their key, one scalar per line.
    static String
    yaml(Map<String,Object> model, String comment)
    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.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • SKIPPED_DIRS

      public static final Set<String> SKIPPED_DIRS
      Directory names never entered by the scan.
  • Method Details

    • scan

      public static TopicRegistry.Scan scan(Path root, int maxFiles) throws IOException
      Scan one root.
      Parameters:
      root - the directory to scan
      maxFiles - the most .adoc files the scan will accept
      Returns:
      the scan result
      Throws:
      IOException - if the tree cannot be read
      IllegalStateException - if the root holds more than maxFiles .adoc files
    • scanFrom

      public static TopicRegistry.Scan scanFrom(Path root, Path rootFile) throws IOException
      Scan from one root file: the file and every .adoc file it reaches through 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 .adoc file (a diagram, a CSV) is passed over. Each file is read once, so an include cycle ends.
      Parameters:
      root - the scan root; registry paths are relative to it
      rootFile - the .adoc file to start from, under root
      Returns:
      the scan result
      Throws:
      IOException - if a file cannot be read
      IllegalArgumentException - if rootFile is not an .adoc file under root
    • domainOf

      public static String domainOf(String id)
      The domain a topic belongs to: the part of its id before the first hyphen, the {domain-prefix}-{slug} rule of IKE-TOPIC-REGISTRY.md.
      Parameters:
      id - the topic id
      Returns:
      the domain id, or the whole id when it has no hyphen
    • model

      public static Map<String,Object> model(List<TopicRegistry.Scan> scans, Path base, Instant now)
      The registry as an ordered map, ready for YAML: the schema's keys first (registry-version, generated, topic-count, domains with their topics), then assemblies, other-files and findings. Topics are grouped by domain and sorted by id. A file path is relative to its root, prefixed with the root when several roots were scanned.
      Parameters:
      scans - the scanned roots
      base - the directory root paths are made relative to (the module base directory)
      now - the generation instant
      Returns:
      the registry model
    • yaml

      public static String yaml(Map<String,Object> model)
      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 load(Path) unchanged.
      Parameters:
      model - the registry model from model(List, Path, Instant)
      Returns:
      the YAML text
    • yaml

      public static String yaml(Map<String,Object> model, String comment)
      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.
      Parameters:
      model - the model, an ordered map of scalars, lists and maps
      comment - the header comment, without the leading #
      Returns:
      the YAML text
    • tree

      public static List<String> tree(TopicRegistry.Scan scan, Path base)
      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.
      Parameters:
      scan - the scan
      base - the directory the root is shown relative to
      Returns:
      the lines, without newlines
    • load

      public static Map<String,Object> load(Path registryFile) throws IOException
      Read a registry written by yaml(Map) back into its model.
      Parameters:
      registryFile - the generated registry file
      Returns:
      the model, with the same shape model(List, Path, Instant) produces
      Throws:
      IOException - if the file cannot be read or is not a generated registry
    • add

      public static List<TopicHeader> add(Map<String,Object> model, Path base, List<Path> files, Instant now) throws IOException
      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.
      Parameters:
      model - the registry model, from model(List, Path, Instant) or load(Path); updated in place
      base - the module base directory the registry's roots are relative to
      files - the files to add, relative to base or absolute; each must be an .adoc file under one of the registry's roots
      now - the update instant, recorded as generated
      Returns:
      the parsed headers of the added files, in the order given
      Throws:
      IOException - if a file cannot be read
      IllegalArgumentException - if a file is missing, is not AsciiDoc, or lies under none of the registry's roots
    • otherEntry

      public static Map<String,Object> otherEntry(TopicHeader o, String fileValue)
      An assembly or plain file: its path, title, document attributes and include count.
      Parameters:
      o - the parsed header of a file that is not a topic
      fileValue - the file path to record
      Returns:
      the registry entry
    • topicEntry

      public static Map<String,Object> topicEntry(TopicHeader t, String fileValue)
      One topic in the registry's field order (id, file, title, type, keywords, status, char-count, dependencies, related, summary, supersedes, notes), then what the header adds: provenance, scope note, citation, license, the anchor and header verdicts, unknown :topic-*: attributes under extra, document attributes, and the include count. Shared with idoc:diff, which generates the registry for each side of a comparison in this same shape.
      Parameters:
      t - the parsed topic header
      fileValue - the file path to record
      Returns:
      the registry entry