fix: a bare admonition style over a paragraph is the label it names

`[NOTE]` over prose and `NOTE: ` in front of it are the same
admonition to Asciidoctor (ADMONITION_STYLES, parser.rb:730), so which
one the author typed is a spelling. The reader now records ONE
admonition node for either, the style line becoming that node's
opening bytes rather than a sibling attribute list, and the printer
writes the label form for both.

WHERE the style line stands decides whether it may be respelled at
all. A bracket line opens a block from any position and a label line
does not, so the fold is refused in item-TEXT position and under a
description item that spent no description of its own: there a label
is more of the item's text and the admonition would be destroyed.
Held to Ruby's five styles exactly and case-sensitively otherwise,
and refused for an interior carrying more than the style, a second
attribute line, a held node between the style and its block, and any
block under it that is not a paragraph.

The three paragraph shapes become one union the held run answers with,
so a paragraph cannot be both an admonition and a styled block, and
the reader names no builder of its own. Seven corpus documents stop
diverging from Asciidoctor's own block structure; the reading net
grows the matching licence, no wider than the routing; the gate gains
an axis that reaches item-text position, where it also asserts what
the confluence property cannot - that formatting a document there
does not change what it renders. The confluence gate loses the
blockFormSpelling/admonition-form row and the blockFormReplay
mechanism with it.

Author: mergeconflict

scripts/block-structure-corpus.json

@@ -2,10 +2,6 @@
   "oracle": "@asciidoctor/core 4.0.11",
   "regenerate": "Measured, not authored: regenerate with `bun run block-structure --write` whenever the oracle pin or the parser moves, then read the diff - it is the artifact that says what a change did to our conformance.",
   "cases": {
-    "api_test.rb#should return false when sections? is called on anything that is not a section#0": {
-      "family": "gap:styled-block-remodel",
-      "signature": "paragraph=>admonition"
-    },
     "attributes_test.rb#id, role and options attributes can be specified on block style using shorthand syntax#0": {
       "family": "gap:styled-block-remodel",
       "signature": "paragraph=>literal"
@@ -14,18 +10,6 @@
       "family": "gap:styled-block-remodel",
       "signature": "paragraph=>literal"
     },
-    "blocks_test.rb#can resolve icon relative to custom iconsdir#0": {
-      "family": "gap:styled-block-remodel",
-      "signature": "paragraph=>admonition"
-    },
-    "blocks_test.rb#can resolve icon relative to default iconsdir#0": {
-      "family": "gap:styled-block-remodel",
-      "signature": "paragraph=>admonition"
-    },
-    "blocks_test.rb#cleans reference to ancestor directories before reading icon if safe mode level is at least SAFE#0": {
-      "family": "gap:styled-block-remodel",
-      "signature": "paragraph=>admonition"
-    },
     "blocks_test.rb#comment style on open block should only skip block#0": {
       "family": "oracle:comment-style",
       "signature": "-pass"
@@ -38,10 +22,6 @@
       "family": "oracle:comment-style",
       "signature": "-paragraph"
     },
-    "blocks_test.rb#does not embed base64-encoded data uri of icon when safe mode level is SECURE or greater#0": {
-      "family": "gap:styled-block-remodel",
-      "signature": "paragraph=>admonition"
-    },
     "blocks_test.rb#dropped image does not break processing of following section and attribute-missing is drop-line#0": {
       "family": "oracle:attribute-missing",
       "signature": "-image"
@@ -50,10 +30,6 @@
       "family": "oracle:attribute-missing",
       "signature": "-image"
     },
-    "blocks_test.rb#embeds base64-encoded data uri of icon when data-uri attribute is set and safe mode level is less than SECURE#0": {
-      "family": "gap:styled-block-remodel",
-      "signature": "paragraph=>admonition"
-    },
     "blocks_test.rb#font-based icon should not override icon specified on admonition#0": {
       "family": "gap:styled-block-remodel",
       "signature": "paragraph=>admonition"
@@ -126,10 +102,6 @@
       "family": "oracle:book-partintro",
       "signature": "paragraph=>open"
     },
-    "blocks_test.rb#should import Font Awesome and use font-based icons when value of icons attribute is font#0": {
-      "family": "gap:styled-block-remodel",
-      "signature": "paragraph=>admonition"
-    },
     "blocks_test.rb#should not allow abstract as direct child of document if doctype is book converted to DocBook#0": {
       "family": "oracle:book-partintro",
       "signature": "paragraph=>open"

scripts/metrics/crossings-registry.json

@@ -118,6 +118,13 @@
     "kind": "vocabulary",
     "reason": "the one read of a bracket line's named values; a table's open asks it rather than splitting the interior a second way"
   },
+  {
+    "file": "src/parse/attrlist.ts",
+    "symbol": "canonicalAttrlist",
+    "importer": "src/parse/lines/open-style.ts",
+    "kind": "vocabulary",
+    "reason": "the one answer to where one attribute inside a bracket line ends, asked here so the style an open acts on is the style the printer would write back"
+  },
   {
     "file": "src/parse/attrlist.ts",
     "symbol": "canonicalAttrlist",
@@ -349,6 +356,13 @@
     "kind": "vocabulary",
     "reason": "pure (line, index) -> Node constructor, in the leaf builder table"
   },
+  {
+    "file": "src/parse/build/paragraph.ts",
+    "symbol": "ParagraphOpening",
+    "importer": "src/parse/lines/held-metadata.ts",
+    "kind": "vocabulary",
+    "reason": "the three shapes a held run can make of the paragraph about to open, decided once by the run and consumed by the builder that reads it"
+  },
   {
     "file": "src/parse/build/paragraph.ts",
     "symbol": "buildAdmonitionParagraph",
@@ -372,10 +386,10 @@
   },
   {
     "file": "src/parse/build/paragraph.ts",
-    "symbol": "buildParagraphFormBlock",
+    "symbol": "buildParagraphNode",
     "importer": "src/parse/lines/reader.ts",
     "kind": "vocabulary",
-    "reason": "pure (variant, tokens, source, index) -> Node constructor for a paragraph a style re-modelled"
+    "reason": "pure (opening, tokens, source, index) -> Node constructor for every paragraph shape, so the reader names no builder of its own"
   },
   {
     "file": "src/parse/build/paragraph.ts",
@@ -937,6 +951,13 @@
     "kind": "vocabulary",
     "reason": "registry reading: which interrupting set an item's own text is read under, named where the two list reads choose between them"
   },
+  {
+    "file": "src/parse/line-shapes.ts",
+    "symbol": "ParagraphContext",
+    "importer": "src/parse/lines/open-style.ts",
+    "kind": "vocabulary",
+    "reason": "the registry's own name for which paragraph is open; the style rules read it rather than restating the set of positions"
+  },
   {
     "file": "src/parse/line-shapes.ts",
     "symbol": "ParagraphContext",

scripts/metrics/score-minimums.json

@@ -395,13 +395,13 @@
     },
     {
       "file": "src/parse/lines/reader.ts",
-      "what": "the LEFT disjunct of the child reader's tailSafe (reader.ts:845 `tailSafe: extent.close !== undefined || tailSafeIn(this.confinement)`) - 3 mutants: -> `true`, -> `false`, and `!==` -> `===`",
+      "what": "the LEFT disjunct of the child reader's tailSafe (reader.ts:837 `tailSafe: extent.close !== undefined || tailSafeIn(this.confinement)`) - 3 mutants: -> `true`, -> `false`, and `!==` -> `===`",
       "class": "never",
       "reason": "EQUIVALENT, measured rather than assumed: all three produce byte-identical output over 66,429 documents (a depth-5 product over `----`, `====`, `--`, `****`, `* a`, `** b`, `+`, blank and `para`) and over all 111,121 list-shape sweep documents. Whenever a block CLOSED, the reader's own `tailSafe` is already true, so the left disjunct never decides. The RIGHT disjunct is live and pinned in tests/format/trailing-continuation.test.ts (a trailing `+` at the end of an unclosed `====` or `--` block comes back), which is what took this file from 93.6 to 94.2"
     },
     {
       "file": "src/parse/lines/reader.ts",
-      "what": "reader.ts:668 `line.continuationTag === \"marker\"` -> `true` in continuationLine's fold arm (#56's new code)",
+      "what": "reader.ts:660 `line.continuationTag === \"marker\"` -> `true` in continuationLine's fold arm (#56's new code)",
       "class": "never",
       "reason": "EQUIVALENT, and worth writing down because the guard IS reached with an untagged `+`. Every `+` that enters an item buffer goes through `pushMarker` and carries the tag, with ONE exception: the `+` that `activeContent` buffers as the attached block's own first line when it stands one blank under an active continuation (`* a` / `+` / blank / `+` is the smallest such document). That untagged cell is only ever the buffer's LAST line, because any line after it takes the `+` arm that blanks it, so the fold the mutant opens there reads exactly the one raw line the leaf arm builds and stops on the same index. Measured: byte-identical output AND byte-identical ASTs over all 111,110 depth-5 sweep documents, byte-identical output over 66,429 delimiter-bearing documents, and an instrumented build reaches the untagged case MID-buffer zero times in either product"
     },

scripts/parity-ledger.ts

@@ -743,6 +743,44 @@ export const OPEN_BLOCK_TILDE_FAMILY = "open-block-tilde";
  */
 const BLOCK_MACRO_NAME_FAMILY = "block-macro-name";
 
+/**
+ * `[NOTE]`/`[TIP]`/`[IMPORTANT]`/`[WARNING]`/`[CAUTION]` over a
+ * paragraph and the bare `STYLE: ` label in front of it are the same
+ * admonition to Asciidoctor (`ADMONITION_STYLES`, parser.rb:730), so
+ * which one the author typed is a spelling; the fold that respells the
+ * bracket form to the label form is `admonitionLabelOpensABlock`
+ * (src/parse/lines/open-style.ts). Every declared case loses the
+ * `blockAttributeList` sibling the bracket style used to open and
+ * gains one admonition node whose opening bytes ARE the style line, so
+ * the bracket line's own bytes move to the label spelling and every
+ * byte after it is unchanged. NOT formatted-only: the node kind
+ * itself changes, the same way `BLOCK_MACRO_NAME_FAMILY` above does.
+ * Not a blanket family either: it does not name a field every node
+ * gained, it names a whole sibling node the fold removes.
+ *
+ * EXPORTED: the standing grid's `under-note-attrlist` container (its
+ * own comment, scripts/shape-registry.ts) puts this style line over
+ * every compound delimiter kind, and
+ * scripts/metrics/shape-census.ts's `admonition-label` GRID_EXEMPT
+ * entry names the same cell in advance as the one place the
+ * delimited-admonition path (`buildDelimitedAdmonition`,
+ * src/parse/build/delimited.ts) is grid-covered - both anticipated
+ * this family's first realized row before this fold existed to
+ * realize it. The witness row
+ * (`fencedCode/under-note-attrlist/minimum-delimiter-inside`) carries
+ * the measured proof rather than an assumption: the harness's own
+ * per-row instrumentation holds `headIdempotent`,
+ * `headRenderEqualsInput`, and `renderNeutral` all true there.
+ *
+ * Matched on the OUTPUTS, not claimed by coordinate
+ * (`admonitionLabelFoldFamily`, scripts/shape-registry-families.ts):
+ * a coordinate names where a shape is generated FROM, not what a
+ * diff there actually is, and a coordinate-only rule would excuse any
+ * future diff at that address rather than only this one mechanism -
+ * the over-broad shape is issue #202's lesson.
+ */
+export const ADMONITION_LABEL_FOLD_FAMILY = "admonition-label-fold";
+
 export const LEDGER_FAMILIES: FamilySets = {
   families: new Set([
     ATTRIBUTE_CONTINUATION_FAMILY,
@@ -786,6 +824,7 @@ export const LEDGER_FAMILIES: FamilySets = {
     TEXTLESS_DESCRIPTION_TEXT_FAMILY,
     OPEN_BLOCK_TILDE_FAMILY,
     BLOCK_MACRO_NAME_FAMILY,
+    ADMONITION_LABEL_FOLD_FAMILY,
   ]),
   formattedOnly: new Set([
     AUTHOR_PLUS_FAMILY,

scripts/shape-diff.ts

@@ -38,6 +38,7 @@ import path from "node:path";
 import { formatAdoc, renderedHtml } from "../tests/helpers.js";
 import { CHILD_MAX_BUFFER, materialize } from "./lib/checkout.js";
 import { cannotRun, GATE_FAILED, printUsage, wantsHelp } from "./lib/cli.js";
+import { admonitionLabelFoldFamily } from "./shape-registry-families.js";
 import { listRunGrid } from "./shape-registry-list-run.js";
 import {
   headingAdjacencyGrid,
@@ -234,9 +235,13 @@ async function reportRow(
   if (byteEqual) {
     return row;
   }
-  if (shape.family !== undefined) {
-    row.family = shape.family;
-  }
+  // The registry's family is a property of the COORDINATE, fixed
+  // before any diff exists; the admonition fold's family is a
+  // property of what the two outputs actually are, so it is tested
+  // here, on the bytes, rather than added to the registry as one more
+  // coordinate claim (issue #202's lesson - see
+  // scripts/shape-registry-families.ts).
+  row.family = shape.family ?? admonitionLabelFoldFamily(baseOut, headOut);
   try {
     row.headIdempotent = (await formatAdoc(headOut)) === headOut;
   } catch (error) {

scripts/shape-registry-families.ts

@@ -25,6 +25,7 @@
  * file's own.
  */
 import {
+  ADMONITION_LABEL_FOLD_FAMILY,
   BLOCK_DELIMITER_LENGTH_FAMILY,
   DESCRIPTION_LIST_ITEM_FAMILY,
   MARKDOWN_THEMATIC_BREAK_FAMILY,
@@ -35,6 +36,57 @@ import {
   UNDERLINED_SECTION_TITLE_FAMILY,
 } from "./parity-ledger.js";
 
+// Ruby's five admonition styles (ADMONITION_STYLES, parser.rb:730),
+// in the bracket spelling a style line carries before the fold.
+const ADMONITION_STYLES: readonly string[] = [
+  "NOTE",
+  "TIP",
+  "IMPORTANT",
+  "WARNING",
+  "CAUTION",
+];
+
+/**
+ * Whether a base/head pair differs by EXACTLY one admonition style
+ * line's fold to its label form: `[STYLE]\n` at the head of `baseOut`
+ * respelled `STYLE: ` at the head of `headOut`, with every byte after
+ * that line identical in both. Tested on the OUTPUTS a diff actually
+ * produced rather than claimed by the coordinate that happened to
+ * realize it first ({@link ADMONITION_LABEL_FOLD_FAMILY}'s own
+ * citation names why - issue #202's lesson): {@link gridRowFamily}
+ * answers by coordinate for the rows below it because each of THOSE
+ * mechanisms is a property of the coordinate itself (a kind the base
+ * registry has no dimension for, a container every row inside moves
+ * for), but the admonition fold is a property of what the printer
+ * wrote, realized at exactly one coordinate today and not chosen
+ * because of it.
+ * @param baseOut - the base revision's formatted output
+ * @param headOut - this checkout's formatted output
+ * @returns the family, or undefined when no admonition style line
+ *   explains the whole difference
+ */
+export function admonitionLabelFoldFamily(
+  baseOut: string,
+  headOut: string,
+): string | undefined {
+  for (const style of ADMONITION_STYLES) {
+    const bracketPrefix = `[${style}]\n`;
+    const labelPrefix = `${style}: `;
+    if (
+      !baseOut.startsWith(bracketPrefix) ||
+      !headOut.startsWith(labelPrefix)
+    ) {
+      continue;
+    }
+    if (
+      baseOut.slice(bracketPrefix.length) === headOut.slice(labelPrefix.length)
+    ) {
+      return ADMONITION_LABEL_FOLD_FAMILY;
+    }
+  }
+  return undefined;
+}
+
 /** The delimiter kind base's registry has no dimension for at all. */
 const OPEN_BLOCK_TILDE_KIND = "openBlockTilde";
 

src/parse/build/metadata.ts

@@ -97,39 +97,26 @@ function buildBlockAttributeList(
 
 /**
  * The bytes between a block attribute line's brackets, taken off in
- * ONE place, so the node's value and the id question below cannot
- * come to disagree about where the interior starts.
+ * ONE place, so every question asked of an interior is asked of the
+ * same bytes the node's value carries.
+ *
+ * Exported for the reading net (tests/lib/reading.ts), which licenses
+ * exactly the respellings {@link buildAttributeLine} and the reader
+ * make of such a line and must therefore ask the interior the same
+ * questions they do rather than cut the brackets its own way. Its src
+ * callers are the two builders below.
  * @param image - a block attribute line, bracket-delimited
  * @returns the interior, brackets excluded
+ * @internal
  */
-function attributeLineInterior(image: string): string {
+export function attributeLineInterior(image: string): string {
   return image.slice(
     BLOCK_ATTR_LIST_PREFIX_LEN,
     // Negated to slice from the end: -1 drops the trailing `]`.
     -BLOCK_ATTR_LIST_SUFFIX_LEN,
   );
 }
 
-/**
- * The id a block attribute LINE names when it names an id and nothing
- * else. THE question, asked in one place by the two consumers that
- * must agree on it: {@link buildAttributeLine} routes on it, and the
- * reading net's projection folds `[#intro]` onto the anchor token
- * because of it.
- *
- * Exported for that net (tests/lib/reading.ts), which must license
- * exactly the respelling this routing makes and no wider one; asking
- * the routing's own question is what keeps the licence from drifting
- * into a second pattern. Its src caller is `buildAttributeLine`,
- * below.
- * @param image - a block attribute line, bracket-delimited
- * @returns the id, or undefined when the line spells anything else
- * @internal
- */
-export function anchorIdOfAttributeLine(image: string): string | undefined {
-  return attrlistAnchorId(attributeLineInterior(image));
-}
-
 /**
  * Builds the node a held `[...]` line becomes: a block anchor when the
  * line names an id and nothing else, an attribute list otherwise.
@@ -150,7 +137,7 @@ export function buildAttributeLine(
   line: Fragment,
   at: LocationIndex,
 ): BlockNode {
-  const id = anchorIdOfAttributeLine(line.image);
+  const id = attrlistAnchorId(attributeLineInterior(line.image));
   return id === undefined
     ? buildBlockAttributeList(line, at)
     : {