diff --git a/CHANGELOG.md b/CHANGELOG.md index d7dcfd5..1595b55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## 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 `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. diff --git a/MIGRATION.md b/MIGRATION.md index dead0a4..e569b1e 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -34,17 +34,20 @@ for (const element of document.querySelectorAll('[data-text-color]')) element.st `htmlToAdf` still reads the HTML `0.3.1` wrote. `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 -`!adf:{localId=…}` marker, where `0.3.1` wrote its directive: +whose only attribute beyond CommonMark's is `localId` in its CommonMark spelling, with the id in an +`!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` | | --- | --- | | `!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: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 -markdown for these directives, or a test pinning its text, needs the new spelling. +`losslessMarkdownToAdf` still reads the directives `0.3.1` wrote, but `0.3.1` can't read a marker, so +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: diff --git a/README.md b/README.md index b90c571..7ccbd6c 100644 --- a/README.md +++ b/README.md @@ -472,7 +472,7 @@ Ping !adf:mention[@Mikael]{id=5b10a2} — !adf:status[In review]{color=yellow} | 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 | -| 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 | | `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 | @@ -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; - 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`; - - 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 document; - carries a node the writers' cause below names, such as an inline card a link marks. diff --git a/docs/decisions.md b/docs/decisions.md index ea52cc5..8b0f9bf 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -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 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, -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 -on the paragraph, the heading and the list, and the maintainer picked: the line above a paragraph, -the end of the last line for one opening a quote or list item, the end of a heading's line, the line -above a list, and each item's id after its marker. Only `localId` rides a marker. A block holding -anything else, or an id with no unambiguous place, keeps its directive, a list whole. The -directives 0.3 wrote for these blocks still read. The grammar: `spec/flavour.md` §The CommonMark -blocks. +the line above a code block, 5 of 7, and a rule's marker with a blank line between it and the rule, +7 of 7. It split 4 to 3 on the paragraph, the heading and the list, and the maintainer picked the +placements `spec/flavour.md` §The CommonMark blocks gives. Only `localId` rides a marker. A block +holding anything else, or an id with no unambiguous place, keeps its directive. The directives 0.3 +wrote for these blocks still read. ## CommonMark is a subset diff --git a/spec/flavour.md b/spec/flavour.md index bf74f6f..3a70984 100644 --- a/spec/flavour.md +++ b/spec/flavour.md @@ -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 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 -stands alone on the line right above it. A rule's stands above a blank line, as does a list's whose -marker cannot interrupt a paragraph (Canonical form): CommonMark reads a line of text above either -as part of it. A list item's stands right after its list marker, one space before its first +stands on the line right above it. A rule's has one blank line between the marker line and the rule, +and so does a list's whose marker cannot interrupt a paragraph (Canonical form): CommonMark reads a +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. ```` @@ -260,9 +260,9 @@ paragraph's text. > Quoted text !adf:{localId=p3} ```` -An empty paragraph or heading holding a `localId` takes the directive form, and so does a list, whole, -one of whose items holds a `localId` beside no first paragraph or opens with a block whose marker -would take the item's first line. A marker anywhere else, holding another key or a value outside +An empty paragraph or heading holding a `localId` takes the directive form. So does a list, whole, +when one of its items holds a `localId` and has no first paragraph, and when one of its items opens +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 lines than these, is a named error, and so is a block carrying two. diff --git a/src/conformance/property-harness.ts b/src/conformance/property-harness.ts index 8e59b1b..ebc39e7 100644 --- a/src/conformance/property-harness.ts +++ b/src/conformance/property-harness.ts @@ -92,7 +92,6 @@ function withoutEmptyKeys(held: T): T { 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 }) function occasionallyIdentified(arbitrary: Arbitrary): Arbitrary { diff --git a/src/markdown/directive/id-marker.test.ts b/src/markdown/directive/id-marker.test.ts index 4167b8e..9efc990 100644 --- a/src/markdown/directive/id-marker.test.ts +++ b/src/markdown/directive/id-marker.test.ts @@ -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]) }) -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=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') }) -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=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') @@ -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') }) -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=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'))]) @@ -217,18 +217,18 @@ test('names an item marker standing before no paragraph', () => { 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:{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('# 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} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alone on its line') - refused('> !adf:{localId=p} Part.\n', '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 }, '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 }, '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 }, 'a line of its own') 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(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))), [ diff --git a/src/markdown/directive/id-marker.ts b/src/markdown/directive/id-marker.ts index 44991f5..6110499 100644 --- a/src/markdown/directive/id-marker.ts +++ b/src/markdown/directive/id-marker.ts @@ -19,7 +19,7 @@ export function spellIdMarker(id: string): string { 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 { for (let start = text.lastIndexOf(trailingOpener); start > 0; start = text.lastIndexOf(trailingOpener, start - 1)) { 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 { const spelled = attributes.get(idKey) if (spelled === undefined || attributes.size !== 1) { - let other = 'nothing' - for (const key of attributes.keys()) if (key !== idKey) other = key - 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 others = [...attributes.keys()].filter((key) => key !== idKey) + 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) } const spelling = spellStringAttribute(spelled.decoded) if (spelling !== spelled.spelling) return failure('unsupported-node-shape', `${type} spells its ${idKey} attribute as ${idKey}=${spelling}`, path) diff --git a/src/markdown/directive/syntax.ts b/src/markdown/directive/syntax.ts index cce4c62..83b0d88 100644 --- a/src/markdown/directive/syntax.ts +++ b/src/markdown/directive/syntax.ts @@ -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 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 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' export const pairFault = `${attributePairCause}; ${directiveEscape}` const prefixFault = `an unescaped ${directivePrefix} completes no directive; ${directiveEscape}` diff --git a/src/markdown/emit/adf-to-markdown.ts b/src/markdown/emit/adf-to-markdown.ts index 2d56b86..f8d52e1 100644 --- a/src/markdown/emit/adf-to-markdown.ts +++ b/src/markdown/emit/adf-to-markdown.ts @@ -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)) } -// 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 } -// 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 { if (!holdsOnlyAttributes(node, [...spelled, idKey])) return undefined 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 })) } -// 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 { const [first] = item.walk.blocks if (first?.node.type === 'paragraph' && first.spelling === 'commonmark') return true diff --git a/src/markdown/parse/blocks.ts b/src/markdown/parse/blocks.ts index 6cce63d..6126daa 100644 --- a/src/markdown/parse/blocks.ts +++ b/src/markdown/parse/blocks.ts @@ -616,7 +616,7 @@ function takeParagraph(walk: Walk): Extract | Paragrap 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 } { return trailed === undefined ? { text } : { text, trailing: trailed.attributes } } diff --git a/src/markdown/parse/markdown-to-adf.ts b/src/markdown/parse/markdown-to-adf.ts index 573fa2d..e622281 100644 --- a/src/markdown/parse/markdown-to-adf.ts +++ b/src/markdown/parse/markdown-to-adf.ts @@ -116,7 +116,7 @@ function markedNode(node: AdfNode, block: Exclude, line: Mar 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 (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) return identified(node, trailing.value, path, block.position) @@ -130,12 +130,12 @@ function lineMarkedNode(node: AdfNode, block: Exclude, line: const gap = block.position.line - line.position.line 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}` - 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) } -// 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): boolean { if (block.kind === 'rule') return true 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 if (first?.kind !== 'marker') return containerNode({ type: 'listItem' }, blocks, reading, path, depth, 'trailing') 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') if (!item.ok) return item