Class AdocDiffMarker

java.lang.Object
network.ike.docs.plugin.diff.AdocDiffMarker
public final class AdocDiffMarker extends Object
Marks the differences between two versions of an AsciiDoc fragment as inline [.diff-ins]#…# / [.diff-del]#…# roles, producing a renderable "marked copy" for a doc-diff review packet (ike-issues#648, #649).

The marker is deliberately conservative. Constructs that inline role markup would corrupt are protected — never marked in place — and their changes are reported in a per-topic change-summary [NOTE] block instead:

  • the header region before the [[anchor]] line (comment header and attribute block);
  • attribute-value continuation lines (trailing backslash);
  • verbatim, listing, passthrough, and table interiors;
  • block-attribute, include, indexterm, anchor, and table-cell lines, and block delimiters;
  • lines carrying inline macros that word-splicing could break (xref:, k:, ((…)), footnote:, image:, …);
  • lines containing the role delimiter character #.

Markable lines get a line-level diff with word-level refinement inside changed line pairs. Because IKE fragments use semantic line breaks, line-level deltas are already clause-grade. Structural prefixes (heading and list markers) are kept outside the role so an inserted heading or list item stays syntactically valid.

All methods are pure functions of their inputs — no I/O — so the marking rules are unit-testable in isolation.

  • Method Details

    • mark

      public static AdocDiffMarker.MarkResult mark(List<String> oldLines, List<String> newLines)
      Produce a marked copy of a changed fragment, without stamps.
      Parameters:
      oldLines - the fragment's lines on the from side
      newLines - the fragment's lines on the to side
      Returns:
      the marked fragment with a change-summary note injected after the level-1 title

    • mark

      public static AdocDiffMarker.MarkResult mark(List<String> oldLines, List<String> newLines, AdocDiffMarker.StampSource stamps)
      Produce a marked copy of a changed fragment, with optional STAMP endnote refs per change boundary.
      Parameters:
      oldLines - the fragment's lines on the from side
      newLines - the fragment's lines on the to side
      stamps - stamp-ref source, or null for no stamps
      Returns:
      the marked fragment with a change-summary note injected after the level-1 title

    • withDiagramHistory

      public static List<String> withDiagramHistory(List<String> oldLines, List<String> markedLines)
      Append, after every diagram block whose body meaningfully changed between the two sides, the compact source delta followed by the rendered previous version — so the reader sees the new drawing, what changed in the spec, and the old drawing, in that order. Blocks are paired per diagram kind in occurrence order; bodies are compared whitespace-insensitively, so formatting-only edits never produce a pair, and diagrams only present on one side are left alone (the change-summary notes already report removed lines).
      Parameters:
      oldLines - the fragment's from-side lines
      markedLines - the marked fragment (its verbatim regions carry the to-side diagram blocks unmodified)
      Returns:
      the marked fragment with delta-plus-previous blocks inserted

    • markAdded

      public static AdocDiffMarker.MarkResult markAdded(List<String> newLines, String fromRef)
      Produce a full-text copy of an added fragment with a banner note instead of inline marks.
      Parameters:
      newLines - the fragment's lines on the to side
      fromRef - the from-side ref name, used in the banner text
      Returns:
      the banner-annotated fragment

    • markAdded

      public static AdocDiffMarker.MarkResult markAdded(List<String> newLines, String fromRef, String stampRef)
      Produce a full-text copy of an added fragment with a banner note, optionally stamped — an added topic is one Active stamp, carried on the banner rather than in the flow.
      Parameters:
      newLines - the fragment's lines on the to side
      fromRef - the from-side ref name, used in the banner text
      stampRef - the stamp footnote macro, or null
      Returns:
      the banner-annotated fragment