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
- **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.
+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.
`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:
+2 -2
View File
@@ -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.
+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
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
+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
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.
-1
View File
@@ -92,7 +92,6 @@ function withoutEmptyKeys<T extends AdfMark | AdfNode>(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<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])
})
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))), [
+3 -4
View File
@@ -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<string> {
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)
+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 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}`
+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))
}
// 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
+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) }
}
// 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> } {
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 (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<Block, MarkerBlock>, 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<Block, MarkerBlock>): 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