3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-19 22:55:44 +01:00

Answer prose round 1: 0 🔴, 12 🟡 (0 misread); reword the marker messages, comments and docs, and name the directive-form exceptions

This commit is contained in:
2026-11-19 17:43:29 +01:00
committed by Lillem4n
parent 57af3c17f2
commit 5945a62b54
12 changed files with 42 additions and 44 deletions
+1 -1
View File
@@ -2,7 +2,7 @@
## Unreleased ## Unreleased
- **Breaking:** `adfToLosslessMarkdown` writes a paragraph, heading, quote, list, list item, code block or rule holding a `localId` in its CommonMark spelling, the id in an `!adf:{localId=…}` marker beside it, where `0.3.1` wrote the block as a directive, so a Jira document reads as markdown. `losslessMarkdownToAdf` still reads the directives `0.3.1` wrote. - **Breaking:** `adfToLosslessMarkdown` writes a paragraph, heading, quote, list, list item, code block or rule holding a `localId` in its CommonMark spelling, with the id in an `!adf:{localId=…}` marker, where `0.3.1` wrote a directive. An empty paragraph or heading, and a list with an item whose id has no first paragraph, keep the directive. `losslessMarkdownToAdf` still reads the directives `0.3.1` wrote; `0.3.1` can't read the markers.
- Add `jiraWikiToAdf`, which reads Jira wiki markup into ADF, `{adf}` macros included, and refuses only a broken `{adf}` macro and markup past the nesting or engine limits. - Add `jiraWikiToAdf`, which reads Jira wiki markup into ADF, `{adf}` macros included, and refuses only a broken `{adf}` macro and markup past the nesting or engine limits.
- Add `adfToLosslessJiraWiki`, which writes ADF as Jira wiki markup and carries each node or mark wiki markup cannot spell in Jira's `{adf}` macro, so nothing is lost. - Add `adfToLosslessJiraWiki`, which writes ADF as Jira wiki markup and carries each node or mark wiki markup cannot spell in Jira's `{adf}` macro, so nothing is lost.
- **Breaking:** `commonMarkToAdf`, `losslessMarkdownToAdf` and `portableMarkdownToAdf` match a link reference to its definition under Unicode case folding, where `0.3.1` lowercased the label. `[ẞ]` with `[SS]: /url` reads as a link, and where two definitions' labels fold together, the first wins. `ı` and `I` stay two labels. - **Breaking:** `commonMarkToAdf`, `losslessMarkdownToAdf` and `portableMarkdownToAdf` match a link reference to its definition under Unicode case folding, where `0.3.1` lowercased the label. `[ẞ]` with `[SS]: /url` reads as a link, and where two definitions' labels fold together, the first wins. `ı` and `I` stay two labels.
+8 -5
View File
@@ -34,17 +34,20 @@ for (const element of document.querySelectorAll('[data-text-color]')) element.st
`htmlToAdf` still reads the HTML `0.3.1` wrote. `htmlToAdf` still reads the HTML `0.3.1` wrote.
`adfToLosslessMarkdown` writes a paragraph, heading, quote, list, list item, code block or rule `adfToLosslessMarkdown` writes a paragraph, heading, quote, list, list item, code block or rule
whose one attribute CommonMark can't spell is `localId` in its CommonMark spelling, the id in an whose only attribute beyond CommonMark's is `localId` in its CommonMark spelling, with the id in an
`!adf:{localId=…}` marker, where `0.3.1` wrote its directive: `!adf:{localId=…}` marker. `0.3.1` wrote it as a directive. An empty paragraph or heading, and a list
with an item whose id has no first paragraph, still take the directive. A quote, code block and rule
take the marker too, placed as `spec/flavour.md` §The CommonMark blocks says:
| `0.3.1` | `0.4.0` | | `0.3.1` | `0.4.0` |
| --- | --- | | --- | --- |
| `!adf:heading {level=2 localId=h1}`, `Background`, `!adf:/heading` | `## Background !adf:{localId=h1}` | | `!adf:heading {level=2 localId=h1}`, `Background`, `!adf:/heading` | `## Background !adf:{localId=h1}` |
| `!adf:paragraph {localId=p1}`, `Text`, `!adf:/paragraph` | `!adf:{localId=p1}` above `Text` | | `!adf:paragraph {localId=p1}`, `Text`, `!adf:/paragraph` | `!adf:{localId=p1}` above `Text` |
| `!adf:bulletList {localId=l1}`, `!adf:listItem {localId=i1}`, … | `!adf:{localId=l1}` above `- !adf:{localId=i1} Item !adf:{localId=p1}` | | `!adf:bulletList {localId=l1}`, `!adf:listItem {localId=i1}`, … | `!adf:{localId=l1}` above `- !adf:{localId=i1} Item` |
`losslessMarkdownToAdf` still reads the directives `0.3.1` wrote. Code that searches stored lossless `losslessMarkdownToAdf` still reads the directives `0.3.1` wrote, but `0.3.1` can't read a marker, so
markdown for these directives, or a test pinning its text, needs the new spelling. upgrade every reader before the writer. Code that searches stored lossless markdown for these
directives, or a test pinning its text, needs the new spelling.
`portableMarkdownToAdf` reads more of GFM's pipe table: `portableMarkdownToAdf` reads more of GFM's pipe table:
+2 -2
View File
@@ -472,7 +472,7 @@ Ping !adf:mention[@Mikael]{id=5b10a2} — !adf:status[In review]{color=yellow}
| ADF | Directive | | ADF | Directive |
| --- | --- | | --- | --- |
| `blockquote`, `bulletList`, `codeBlock`, `heading`, `listItem`, `orderedList`, `paragraph`, `rule` carrying `localId` | the CommonMark spelling with a marker: `!adf:{localId=…}` on the line above, after a list item's marker, or at the end of a heading's line and of the last line of a quote's or list item's first paragraph | | `blockquote`, `bulletList`, `codeBlock`, `heading`, `listItem`, `orderedList`, `paragraph`, `rule` carrying `localId` | the CommonMark spelling with a marker: `!adf:{localId=…}` on the line above, after a list item's marker, or at the end of a heading's line and of the last line of a quote's or list item's first paragraph |
| the same nodes carrying marks or a value neither CommonMark nor a marker spells | the same node in directive form, `!adf:paragraph {marks=…}` | | the same nodes carrying marks, another attribute or a value neither CommonMark nor a marker spells, an empty paragraph or heading carrying `localId`, and a list with an item whose `localId` has no first paragraph to sit beside | the same node in directive form, `!adf:paragraph {marks=…}` |
| `border` | an inline directive mark around a `mediaInline`, the one inline node that takes it | | `border` | an inline directive mark around a `mediaInline`, the one inline node that takes it |
| `caption`, `media`, `mediaGroup`, `mediaSingle` | the media family; an image CommonMark cannot spell, a stored file, a caption | | `caption`, `media`, `mediaGroup`, `mediaSingle` | the media family; an image CommonMark cannot spell, a stored file, a caption |
| `date`, `emoji`, `inlineCard`, `mediaInline`, `mention`, `status` | inline leaves; `emoji`, `mention` and `status` spell their `text` in the `[content]` slot | | `date`, `emoji`, `inlineCard`, `mediaInline`, `mention`, `status` | inline leaves; `emoji`, `mention` and `status` spell their `text` in the `[content]` slot |
@@ -702,7 +702,7 @@ Every call can raise `engine-limit`, and every conversion `unsupported-nesting-d
such as `[!adf:status[Done]{color=green}](/u)`: write the link around text beside them; such as `[!adf:status[Done]{color=green}](/u)`: write the link around text beside them;
- writes as a directive a node or mark the lossless flavour spells as CommonMark, other than the - writes as a directive a node or mark the lossless flavour spells as CommonMark, other than the
directive `0.3` wrote for a block holding a `localId`; directive `0.3` wrote for a block holding a `localId`;
- puts an `!adf:{…}` marker where its block carries none, or gives it a key but `localId`; - puts an `!adf:{…}` marker above or beside a block that takes its id another way, or gives it a key other than `localId`;
- puts `!adf:textBreak{}` where it parts nothing, or `!adf:doc` anywhere but as the whole - puts `!adf:textBreak{}` where it parts nothing, or `!adf:doc` anywhere but as the whole
document; document;
- carries a node the writers' cause below names, such as an inline card a link marks. - carries a node the writers' cause below names, such as an inline card a link marks.
+5 -7
View File
@@ -208,13 +208,11 @@ description read as mostly `!adf:` lines, and a `- x` typed into a directive lis
than added an item. The id rides the nameless attribute block `!adf:{localId=…}` instead, beside than added an item. The id rides the nameless attribute block `!adf:{localId=…}` instead, beside
the block's CommonMark spelling; the maintainer chose the nameless form. A writer panel of seven the block's CommonMark spelling; the maintainer chose the nameless form. A writer panel of seven
readers seated from README §Audience settled three placements: the line above a blockquote, 5 of 7, readers seated from README §Audience settled three placements: the line above a blockquote, 5 of 7,
the line above a code block, 5 of 7, and a rule's line above a blank line, 7 of 7. It split 4 to 3 the line above a code block, 5 of 7, and a rule's marker with a blank line between it and the rule,
on the paragraph, the heading and the list, and the maintainer picked: the line above a paragraph, 7 of 7. It split 4 to 3 on the paragraph, the heading and the list, and the maintainer picked the
the end of the last line for one opening a quote or list item, the end of a heading's line, the line placements `spec/flavour.md` §The CommonMark blocks gives. Only `localId` rides a marker. A block
above a list, and each item's id after its marker. Only `localId` rides a marker. A block holding holding anything else, or an id with no unambiguous place, keeps its directive. The directives 0.3
anything else, or an id with no unambiguous place, keeps its directive, a list whole. The wrote for these blocks still read.
directives 0.3 wrote for these blocks still read. The grammar: `spec/flavour.md` §The CommonMark
blocks.
## CommonMark is a subset ## CommonMark is a subset
+6 -6
View File
@@ -245,9 +245,9 @@ alone on the line right above it, inside its container's prefix or indentation;
opening a quote or a list item spelled in CommonMark ends its last line with its marker instead, one opening a quote or a list item spelled in CommonMark ends its last line with its marker instead, one
space after its text, since the line above is the container's. A heading's ends its line, one space space after its text, since the line above is the container's. A heading's ends its line, one space
after its text: `## Background !adf:{localId=h1}`. A blockquote's, a code block's and a list's after its text: `## Background !adf:{localId=h1}`. A blockquote's, a code block's and a list's
stands alone on the line right above it. A rule's stands above a blank line, as does a list's whose stands on the line right above it. A rule's has one blank line between the marker line and the rule,
marker cannot interrupt a paragraph (Canonical form): CommonMark reads a line of text above either and so does a list's whose marker cannot interrupt a paragraph (Canonical form): CommonMark reads a
as part of it. A list item's stands right after its list marker, one space before its first line of text above either as part of it. A list item's stands right after its list marker, one space before its first
paragraph's text. paragraph's text.
```` ````
@@ -260,9 +260,9 @@ paragraph's text.
> Quoted text !adf:{localId=p3} > Quoted text !adf:{localId=p3}
```` ````
An empty paragraph or heading holding a `localId` takes the directive form, and so does a list, whole, An empty paragraph or heading holding a `localId` takes the directive form. So does a list, whole,
one of whose items holds a `localId` beside no first paragraph or opens with a block whose marker when one of its items holds a `localId` and has no first paragraph, and when one of its items opens
would take the item's first line. A marker anywhere else, holding another key or a value outside with a block whose own marker would take the item's first line. A marker anywhere else, holding another key or a value outside
its canonical spelling, standing above no block of its container, or parted from its block by other its canonical spelling, standing above no block of its container, or parted from its block by other
lines than these, is a named error, and so is a block carrying two. lines than these, is a named error, and so is a block carrying two.
-1
View File
@@ -92,7 +92,6 @@ function withoutEmptyKeys<T extends AdfMark | AdfNode>(held: T): T {
return kept return kept
} }
// Jira gives every block an id, which the lossless writer carries in a marker beside the block's CommonMark spelling.
const localId = fc.oneof({ arbitrary: fc.stringMatching(/^[0-9a-f-]{1,12}$/), weight: 3 }, { arbitrary: textOf(0), weight: 1 }) const localId = fc.oneof({ arbitrary: fc.stringMatching(/^[0-9a-f-]{1,12}$/), weight: 3 }, { arbitrary: textOf(0), weight: 1 })
function occasionallyIdentified(arbitrary: Arbitrary<AdfNode>): Arbitrary<AdfNode> { function occasionallyIdentified(arbitrary: Arbitrary<AdfNode>): Arbitrary<AdfNode> {
+9 -9
View File
@@ -173,13 +173,13 @@ test('names a marker with no block below it to carry its id', () => {
assert.deepEqual(errorPath(losslessMarkdownToAdf('Part.\n\n> !adf:{localId=p}\n')), ['content', 1, 'content', 0]) assert.deepEqual(errorPath(losslessMarkdownToAdf('Part.\n\n> !adf:{localId=p}\n')), ['content', 1, 'content', 0])
}) })
test('names the blank line a marker and its block keep or leave out', () => { test('refuses a marker whose blank line does not match its block', () => {
refused('!adf:{localId=p}\n\nPart.\n', 'malformed-directive', { line: 1, offset: 0 }, 'right above') refused('!adf:{localId=p}\n\nPart.\n', 'malformed-directive', { line: 1, offset: 0 }, 'right above')
refused('!adf:{localId=r}\n---\n', 'malformed-directive', { line: 1, offset: 0 }, 'blank line') refused('!adf:{localId=r}\n---\n', 'malformed-directive', { line: 1, offset: 0 }, 'blank line')
refused('!adf:{localId=l}\n2. a\n', 'malformed-directive', { line: 1, offset: 0 }, 'blank line') refused('!adf:{localId=l}\n2. a\n', 'malformed-directive', { line: 1, offset: 0 }, 'blank line')
}) })
test('names the block a marker line stands above that carries its id another way, or not at all', () => { test('refuses a marker line above a block that takes its id another way or has none', () => {
refused('!adf:{localId=h}\n# Part\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'heading', 'end of its line') refused('!adf:{localId=h}\n# Part\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'heading', 'end of its line')
refused('> !adf:{localId=p}\n> Part.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'end of its last line') refused('> !adf:{localId=p}\n> Part.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'end of its last line')
refused('- !adf:{localId=p}\n Part.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'list item') refused('- !adf:{localId=p}\n Part.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'list item')
@@ -200,7 +200,7 @@ test('names a trailing marker standing where the id takes the line above, or on
refused('## Part\t!adf:{localId=h}\n', 'malformed-directive', { line: 1, offset: 0 }, 'completes no directive') refused('## Part\t!adf:{localId=h}\n', 'malformed-directive', { line: 1, offset: 0 }, 'completes no directive')
}) })
test('reads a trailing marker ahead of the link reference definitions and the setext underline its paragraph holds', () => { test('reads a trailing marker before the link reference definitions and the setext underline of its paragraph', () => {
refused('> [a]: /u !adf:{localId=p}\n', 'malformed-directive', { line: 1, offset: 0 }, 'link reference definitions') refused('> [a]: /u !adf:{localId=p}\n', 'malformed-directive', { line: 1, offset: 0 }, 'link reference definitions')
refused('[a]: /u !adf:{localId=h}\n===\n', 'malformed-directive', { line: 1, offset: 0 }, 'link reference definitions') refused('[a]: /u !adf:{localId=h}\n===\n', 'malformed-directive', { line: 1, offset: 0 }, 'link reference definitions')
assert.deepEqual(read(losslessMarkdownToAdf('Part !adf:{localId=h}\n===\n')), [node('heading', { level: 1, localId: 'h' }, text('Part'))]) assert.deepEqual(read(losslessMarkdownToAdf('Part !adf:{localId=h}\n===\n')), [node('heading', { level: 1, localId: 'h' }, text('Part'))])
@@ -217,18 +217,18 @@ test('names an item marker standing before no paragraph', () => {
test('names a marker spelled outside its one canonical form', () => { test('names a marker spelled outside its one canonical form', () => {
refused('!adf:{localId="p"}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId=p') refused('!adf:{localId="p"}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId=p')
refused('!adf:{level=2}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'level') refused('!adf:{level=2}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'level')
refused('!adf:{}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'carries nothing') refused('!adf:{}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'no key')
refused('- !adf:{localId=i style=x} Part\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'style') refused('- !adf:{localId=i style=x} Part\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'style')
refused('# Part !adf:{localId="h"}\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId=h') refused('# Part !adf:{localId="h"}\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId=h')
refused('!adf:{localId=p b=1}\nPart.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alphabetical') refused('!adf:{localId=p b=1}\nPart.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alphabetical')
refused('!adf:{localId=p} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alone on its line') refused('!adf:{localId=p} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'a line of its own')
refused('> !adf:{localId=p} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alone on its line') refused('> !adf:{localId=p} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'a line of its own')
for (const item of ['- !adf:{localId=i}Part\n', '- !adf:{localId=i} Part\n', '- !adf:{localId=i} \tPart\n']) refused(item, 'malformed-directive', { line: 1, offset: 0 }, 'alone on its line') for (const item of ['- !adf:{localId=i}Part\n', '- !adf:{localId=i} Part\n', '- !adf:{localId=i} \tPart\n']) refused(item, 'malformed-directive', { line: 1, offset: 0 }, 'a line of its own')
refused('- !adf:{localId=i Part\n', 'malformed-directive', { line: 1, offset: 0 }, 'key=value') refused('- !adf:{localId=i Part\n', 'malformed-directive', { line: 1, offset: 0 }, 'key=value')
refused('!adf:{a=1 localId=p}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'carries a;') refused('!adf:{a=1 localId=p}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'holds a;')
}) })
test('leaves a marker the text it is in the readers claiming no directive, and writes none there', () => { test('reads an `!adf:{…}` as text where the reader claims no directive, and the portable writer drops the ids', () => {
assert.deepEqual(read(portableMarkdownToAdf('!adf:{localId=p}\nPart.\n')), [said(undefined, '!adf:{localId=p} Part.')]) assert.deepEqual(read(portableMarkdownToAdf('!adf:{localId=p}\nPart.\n')), [said(undefined, '!adf:{localId=p} Part.')])
assert.deepEqual(read(commonMarkToAdf('- !adf:{localId=i} Part !adf:{localId=p}\n')), [node('bulletList', {}, node('listItem', {}, said(undefined, '!adf:{localId=i} Part !adf:{localId=p}')))]) assert.deepEqual(read(commonMarkToAdf('- !adf:{localId=i} Part !adf:{localId=p}\n')), [node('bulletList', {}, node('listItem', {}, said(undefined, '!adf:{localId=i} Part !adf:{localId=p}')))])
assert.equal(written(adfToPortableMarkdown(document(...jiraDescription))), [ assert.equal(written(adfToPortableMarkdown(document(...jiraDescription))), [
+3 -4
View File
@@ -19,7 +19,7 @@ export function spellIdMarker(id: string): string {
return `${directivePrefix}${spellIdAttributes(id)}` return `${directivePrefix}${spellIdAttributes(id)}`
} }
// A quoted id may hold the opener, so the marker is the last opener whose attributes end the text; one at the start would trail nothing. // A quoted id may hold the opener, so the marker is the last opener whose attributes end the text; an opener at index 0 has no text before it, so it is no trailing marker.
export function readTrailingMarker(text: string): TrailingMarker | undefined { export function readTrailingMarker(text: string): TrailingMarker | undefined {
for (let start = text.lastIndexOf(trailingOpener); start > 0; start = text.lastIndexOf(trailingOpener, start - 1)) { for (let start = text.lastIndexOf(trailingOpener); start > 0; start = text.lastIndexOf(trailingOpener, start - 1)) {
const read = readAttributes(text, start + trailingOpener.length - 1, pairFault) const read = readAttributes(text, start + trailingOpener.length - 1, pairFault)
@@ -45,9 +45,8 @@ export function readItemMarker(text: string): { attributes: DirectiveAttributes;
export function readMarkerId(attributes: DirectiveAttributes, type: string, path: ConvertErrorPath): Result<string> { export function readMarkerId(attributes: DirectiveAttributes, type: string, path: ConvertErrorPath): Result<string> {
const spelled = attributes.get(idKey) const spelled = attributes.get(idKey)
if (spelled === undefined || attributes.size !== 1) { if (spelled === undefined || attributes.size !== 1) {
let other = 'nothing' const others = [...attributes.keys()].filter((key) => key !== idKey)
for (const key of attributes.keys()) if (key !== idKey) other = key return failure('unsupported-node-shape', `an ${markerOpener}…} marker holds ${idKey} alone: this one on a ${type} holds ${others.length === 0 ? 'no key' : others.join(', ')}; write the ${type} as its directive to carry more`, path)
return failure('unsupported-node-shape', `an ${markerOpener}…} marker carries ${idKey} alone: this one on a ${type} carries ${other}; write the ${type} as its directive to carry more`, path)
} }
const spelling = spellStringAttribute(spelled.decoded) const spelling = spellStringAttribute(spelled.decoded)
if (spelling !== spelled.spelling) return failure('unsupported-node-shape', `${type} spells its ${idKey} attribute as ${idKey}=${spelling}`, path) if (spelling !== spelled.spelling) return failure('unsupported-node-shape', `${type} spells its ${idKey} attribute as ${idKey}=${spelling}`, path)
+1 -1
View File
@@ -65,7 +65,7 @@ export const directiveEscape = `\\${directivePrefix} keeps the prefix literal`
const closerFault = `a closer carries nothing after its name: this one does; ${directiveEscape}` const closerFault = `a closer carries nothing after its name: this one does; ${directiveEscape}`
const emptyFault = 'an empty {attrs} is omitted unless the { itself claims the directive: this one spells {}' const emptyFault = 'an empty {attrs} is omitted unless the { itself claims the directive: this one spells {}'
const openerFault = `a directive opener reads a name, one bare argument and {attrs}, one space apart: this one does not; ${directiveEscape}` const openerFault = `a directive opener reads a name, one bare argument and {attrs}, one space apart: this one does not; ${directiveEscape}`
const markerFault = `an ${markerOpener}…} marker stands alone on its line, after a list item's marker or at the end of a paragraph's or heading's last line: this one does not; ${directiveEscape}` const markerFault = `an ${markerOpener}…} marker stands on a line of its own, right after a list item's marker, or at the end of a paragraph's or heading's last line: this one does none of these; ${directiveEscape}`
const orderFault = 'the {attrs} keys read in alphabetical order' const orderFault = 'the {attrs} keys read in alphabetical order'
export const pairFault = `${attributePairCause}; ${directiveEscape}` export const pairFault = `${attributePairCause}; ${directiveEscape}`
const prefixFault = `an unescaped ${directivePrefix} completes no directive; ${directiveEscape}` const prefixFault = `an unescaped ${directivePrefix} completes no directive; ${directiveEscape}`
+2 -3
View File
@@ -258,10 +258,9 @@ export function quotedBlocks(node: AdfNode, path: ConvertErrorPath, depth: numbe
return success(commonMarkText(markedLines(id, quotedText(bodyText(joinBlocks(inner.value.blocks, 'quote'))), false), inner.value.headroom)) return success(commonMarkText(markedLines(id, quotedText(bodyText(joinBlocks(inner.value.blocks, 'quote'))), false), inner.value.headroom))
} }
// The id a marker carries beside a CommonMark spelling holding the attributes `spelled` names; `undefined` where the node holds another attribute, or an id no marker carries.
type MarkedId = { id?: string } type MarkedId = { id?: string }
// The portable reduction drops every id, so only the lossless writer meets one. // The id a marker holds beside a CommonMark spelling of the attributes `spelled` names; `undefined` where the node holds another attribute, or an id no marker holds. The portable reduction drops every id, so only the lossless writer meets one.
function markedId(node: AdfNode, ...spelled: string[]): MarkedId | undefined { function markedId(node: AdfNode, ...spelled: string[]): MarkedId | undefined {
if (!holdsOnlyAttributes(node, [...spelled, idKey])) return undefined if (!holdsOnlyAttributes(node, [...spelled, idKey])) return undefined
const id = nodeAttrs(node)[idKey] const id = nodeAttrs(node)[idKey]
@@ -358,7 +357,7 @@ function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, writing:
return emitDirectiveBlock(node, ordered ? blockNodes.orderedList : blockNodes.bulletList, path, depth, () => success({ blocks: directiveItems(walked), headroom: headroom - 1 })) return emitDirectiveBlock(node, ordered ? blockNodes.orderedList : blockNodes.bulletList, path, depth, () => success({ blocks: directiveItems(walked), headroom: headroom - 1 }))
} }
// The line after an item's marker holds its own id, so an item whose first block takes the line above for its id, or whose id stands beside no paragraph, has no CommonMark spelling. // An item's id sits right after its list marker, before its first paragraph's text. An item has no CommonMark spelling when its first block would put its own marker on that line, or when it has an id and no first paragraph.
function holdsItemMarker(item: WalkedItem): boolean { function holdsItemMarker(item: WalkedItem): boolean {
const [first] = item.walk.blocks const [first] = item.walk.blocks
if (first?.node.type === 'paragraph' && first.spelling === 'commonmark') return true if (first?.node.type === 'paragraph' && first.spelling === 'commonmark') return true
+1 -1
View File
@@ -616,7 +616,7 @@ function takeParagraph(walk: Walk): Extract<Block, { kind: 'fault' }> | Paragrap
return { kind: 'paragraph', position: kept?.position ?? leaf.position, ...trailedText(text, trailed) } return { kind: 'paragraph', position: kept?.position ?? leaf.position, ...trailedText(text, trailed) }
} }
// No trailing key where no marker trails, so a block reads as it did before markers. // A block holding no marker has no `trailing` key.
function trailedText(text: string, trailed: TrailingMarker | undefined): { text: string; trailing?: Read<DirectiveAttributes> } { function trailedText(text: string, trailed: TrailingMarker | undefined): { text: string; trailing?: Read<DirectiveAttributes> } {
return trailed === undefined ? { text } : { text, trailing: trailed.attributes } return trailed === undefined ? { text } : { text, trailing: trailed.attributes }
} }
+4 -4
View File
@@ -116,7 +116,7 @@ function markedNode(node: AdfNode, block: Exclude<Block, MarkerBlock>, line: Mar
if (trailing.fault !== undefined) return positioned(faulted(trailing.fault, path), block.position) if (trailing.fault !== undefined) return positioned(faulted(trailing.fault, path), block.position)
if (line !== undefined) return positioned(failure('malformed-directive', twoMarkers, path), block.position) if (line !== undefined) return positioned(failure('malformed-directive', twoMarkers, path), block.position)
if (block.kind === 'paragraph' && !trails) { if (block.kind === 'paragraph' && !trails) {
return positioned(failure('unsupported-node-shape', `a paragraph carries its ${markerOpener}…} marker on the line above it, unless it opens a quote or a list item: move this one there`, path), block.position) return positioned(failure('unsupported-node-shape', `a paragraph carries its ${markerOpener}…} marker on the line above it, unless it opens a quote or a list item: move this one to the line above the paragraph`, path), block.position)
} }
if (node.type !== block.kind) return positioned(failure('unsupported-node-shape', `this paragraph reads as a ${node.type}, whose id rides its directive: write the ${node.type} as its directive`, path), block.position) if (node.type !== block.kind) return positioned(failure('unsupported-node-shape', `this paragraph reads as a ${node.type}, whose id rides its directive: write the ${node.type} as its directive`, path), block.position)
return identified(node, trailing.value, path, block.position) return identified(node, trailing.value, path, block.position)
@@ -130,12 +130,12 @@ function lineMarkedNode(node: AdfNode, block: Exclude<Block, MarkerBlock>, line:
const gap = block.position.line - line.position.line const gap = block.position.line - line.position.line
if (gap !== (blankBelowMarker(block) ? 2 : 1)) { if (gap !== (blankBelowMarker(block) ? 2 : 1)) {
const placement = blankBelowMarker(block) ? `one blank line parts an ${markerOpener}…} marker from the ${node.type} below it, which CommonMark would otherwise read with the marker` : `an ${markerOpener}…} marker stands on the line right above its ${node.type}` const placement = blankBelowMarker(block) ? `one blank line parts an ${markerOpener}…} marker from the ${node.type} below it, which CommonMark would otherwise read with the marker` : `an ${markerOpener}…} marker stands on the line right above its ${node.type}`
return positioned(failure('malformed-directive', `${placement}: this one stands ${gap} lines above it`, path), line.position) return positioned(failure('malformed-directive', `${placement}: this one stands ${gap === 1 ? '1 line' : `${gap} lines`} above it`, path), line.position)
} }
return identified(node, line.attributes, path, line.position) return identified(node, line.attributes, path, line.position)
} }
// A text line above a rule makes a setext heading, and one above a list its marker cannot interrupt continues the line. // A text line above a rule makes a setext heading, and above a list whose marker cannot interrupt a paragraph it continues that paragraph.
function blankBelowMarker(block: Exclude<Block, MarkerBlock>): boolean { function blankBelowMarker(block: Exclude<Block, MarkerBlock>): boolean {
if (block.kind === 'rule') return true if (block.kind === 'rule') return true
if (block.kind !== 'bulletList' && block.kind !== 'orderedList') return false if (block.kind !== 'bulletList' && block.kind !== 'orderedList') return false
@@ -297,7 +297,7 @@ function listItemNode(blocks: readonly Block[], reading: Reading, path: ConvertE
const [first] = blocks const [first] = blocks
if (first?.kind !== 'marker') return containerNode({ type: 'listItem' }, blocks, reading, path, depth, 'trailing') if (first?.kind !== 'marker') return containerNode({ type: 'listItem' }, blocks, reading, path, depth, 'trailing')
if (first.placement === 'line') { if (first.placement === 'line') {
return positioned(failure('unsupported-node-shape', `a list item's first line carries the item's own ${markerOpener}…} marker, right after its list marker: write the list as directives to give the block opening this item an id`, path), first.position) return positioned(failure('unsupported-node-shape', `a list item's first line carries the item's own ${markerOpener}…} marker, right after its list marker: write the list as directives, or end a paragraph opening this item with a marker, to give the block opening this item an id`, path), first.position)
} }
const item = containerNode({ type: 'listItem' }, blocks.slice(1), reading, path, depth, 'trailing') const item = containerNode({ type: 'listItem' }, blocks.slice(1), reading, path, depth, 'trailing')
if (!item.ok) return item if (!item.ok) return item