mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-20 07:05:44 +01:00
Answer product-owner round 1: an emphasis or link run spans an unmarked hard break, the recipe drops a hard break's marks, and the refusal names hard breaks
This commit is contained in:
+10
-3
@@ -26,13 +26,20 @@ npm install @larvit/adf-codec@0.2.0 adf-codec-0.1@npm:@larvit/adf-codec@0.1.0
|
|||||||
```
|
```
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import { adfToLosslessMarkdown } from '@larvit/adf-codec'
|
import { adfToLosslessMarkdown, type AdfNode } from '@larvit/adf-codec'
|
||||||
import { markdownToAdf as markdownToAdf010 } from 'adf-codec-0.1'
|
import { markdownToAdf as markdownToAdf010 } from 'adf-codec-0.1'
|
||||||
|
|
||||||
|
// 0.1.0 gave a hard break the marks spelled around it; Atlassian's schema gives it none.
|
||||||
|
function unmarkHardBreaks(node: AdfNode): AdfNode {
|
||||||
|
const { marks, ...unmarked } = node
|
||||||
|
if (node.type === 'hardBreak') return unmarked
|
||||||
|
return node.content === undefined ? node : { ...node, content: node.content.map(unmarkHardBreaks) }
|
||||||
|
}
|
||||||
|
|
||||||
function migrateMarkdown(stored: string) {
|
function migrateMarkdown(stored: string) {
|
||||||
const parsed = markdownToAdf010(stored)
|
const parsed = markdownToAdf010(stored)
|
||||||
// 0.1.0 dropped an empty content array, so a document with no content key meant an empty one.
|
// 0.1.0 dropped an empty content array, so a document with no content key meant an empty one.
|
||||||
return parsed.ok ? adfToLosslessMarkdown({ ...parsed.value, content: parsed.value.content ?? [] }) : parsed
|
return parsed.ok ? adfToLosslessMarkdown({ ...parsed.value, content: (parsed.value.content ?? []).map(unmarkHardBreaks) }) : parsed
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -66,7 +73,7 @@ Markdown the spelling table leaves alone, which `0.2.0` reads as a different doc
|
|||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| a link whose text already holds one (`[a<https://example.com/>b](/v)`) | marks every node the inner link does not, splitting the outer link around it | leaves the outer brackets literal text; write the pieces as separate links to keep them |
|
| a link whose text already holds one (`[a<https://example.com/>b](/v)`) | marks every node the inner link does not, splitting the outer link around it | leaves the outer brackets literal text; write the pieces as separate links to keep them |
|
||||||
| markdown holding no block (`""`) | `{ type: 'doc', version: 1 }` | `{ content: [], type: 'doc', version: 1 }`; `!adf:doc {content=none}` reads as the former |
|
| markdown holding no block (`""`) | `{ type: 'doc', version: 1 }` | `{ content: [], type: 'doc', version: 1 }`; `!adf:doc {content=none}` reads as the former |
|
||||||
| a hard break inside a mark's spelling (`*a\` then `b*` on the next line) | the hard break holds the mark | the hard break holds no marks, as Atlassian's schema requires; converting per the recipe above keeps a stored one's marks in the inline carry. A link whose text is only a hard break reads as its destination linked |
|
| a hard break inside a mark's spelling (`*a\` then `b*` on the next line) | the hard break holds the mark | the hard break holds no marks, as Atlassian's schema requires, and the recipe above drops them from stored markdown. A link whose text is only hard breaks reads as its destination linked |
|
||||||
| a link whose text is empty (`[](/url)`, `[]()`) | literal text | `/url` linked to `/url`, and nothing where the destination is empty too |
|
| a link whose text is empty (`[](/url)`, `[]()`) | literal text | `/url` linked to `/url`, and nothing where the destination is empty too |
|
||||||
| a code fence whose info string opens `adf:` (```` ```adf:x ````) | a `codeBlock` with that language | in `losslessMarkdownToAdf`, the block carry, refusing a body that is not one node's canonical JSON; write `!adf:codeBlock {language="adf:x"}` around a bare fence to keep the code block |
|
| a code fence whose info string opens `adf:` (```` ```adf:x ````) | a `codeBlock` with that language | in `losslessMarkdownToAdf`, the block carry, refusing a body that is not one node's canonical JSON; write `!adf:codeBlock {language="adf:x"}` around a bare fence to keep the code block |
|
||||||
|
|
||||||
|
|||||||
@@ -215,7 +215,7 @@ emit refuses:
|
|||||||
| Code | Fires when | What you can do |
|
| Code | Fires when | What you can do |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `unsupported-nesting-depth` | blocks, marks, an attribute's JSON or a carried node's JSON nest past 500 levels | keep the ADF and pass the document over, or show it read-only; flatten the input where you are the one who wrote it |
|
| `unsupported-nesting-depth` | blocks, marks, an attribute's JSON or a carried node's JSON nest past 500 levels | keep the ADF and pass the document over, or show it read-only; flatten the input where you are the one who wrote it |
|
||||||
| `unsupported-node-shape` | parsing, in `losslessMarkdownToAdf`: markdown spells a node with an attribute, value, argument or body its type does not take, or without one it needs, writes as a directive a node or mark the lossless flavour spells as CommonMark, or puts a reserved directive out of place: `!adf:textBreak{}` or `!adf:listBreak` parting nothing, `!adf:doc` anywhere but as the whole document. Emitting: a node carrying one mark type twice, unless it rides the carry, a block or a non-text inline node holding `text`, or a leaf block or a non-text inline node holding `content` | fix what the message names; `spec/flavour.md` lists every type's attributes and body |
|
| `unsupported-node-shape` | parsing, in `losslessMarkdownToAdf`: markdown spells a node with an attribute, value, argument or body its type does not take, or without one it needs, wraps a directive mark around nothing or only hard breaks, writes as a directive a node or mark the lossless flavour spells as CommonMark, or puts a reserved directive out of place: `!adf:textBreak{}` or `!adf:listBreak` parting nothing, `!adf:doc` anywhere but as the whole document. Emitting: a node carrying one mark type twice, unless it rides the carry, a block or a non-text inline node holding `text`, or a leaf block or a non-text inline node holding `content` | fix what the message names; `spec/flavour.md` lists every type's attributes and body |
|
||||||
|
|
||||||
## The guarantees
|
## The guarantees
|
||||||
|
|
||||||
|
|||||||
+3
-2
@@ -205,8 +205,9 @@ where its reference implementation nests one `<a>` in another.
|
|||||||
## An image reads as an image only alone in its paragraph, else as its alt text linked; a link text holding nothing a mark rides reads as its destination
|
## An image reads as an image only alone in its paragraph, else as its alt text linked; a link text holding nothing a mark rides reads as its destination
|
||||||
|
|
||||||
2026-10-04, the maintainer and a writer panel, 3 of 3; `[]()` 2026-10-09, by Goals 4 and 7, as the
|
2026-10-04, the maintainer and a writer panel, 3 of 3; `[]()` 2026-10-09, by Goals 4 and 7, as the
|
||||||
maintainer's plan item asked; a link text of hard breaks alone 2026-10-09, by Goal 7. Goals 4, 5, 6 and 7. Valid while `mediaInline` carries no URL and ADF
|
maintainer's plan item asked; a link text of hard breaks alone 2026-10-09, by Goal 7. Goals 4, 5, 6
|
||||||
holds no empty text node.
|
and 7. Valid while `mediaInline` carries no URL, ADF holds no empty text node and a hard break takes
|
||||||
|
no marks.
|
||||||
|
|
||||||
Every reader reads every CommonMark image and empty link, as `spec/flavour.md` §The CommonMark image
|
Every reader reads every CommonMark image and empty link, as `spec/flavour.md` §The CommonMark image
|
||||||
and §Marks spell out. An image alone in its paragraph reads as the image, its title as the caption.
|
and §Marks spell out. An image alone in its paragraph reads as the image, its title as the caption.
|
||||||
|
|||||||
+4
-3
@@ -538,9 +538,10 @@ gives no marks, and nesting is the marks array in order, outermost first: `_!adf
|
|||||||
gives marks `[em, underline]`, `!adf:underline[_x_]` the reverse. `adfToLosslessMarkdown` nests in
|
gives marks `[em, underline]`, `!adf:underline[_x_]` the reverse. `adfToLosslessMarkdown` nests in
|
||||||
the order the array holds rather than sorting it — `docs/decisions.md` §Equality is deep restores
|
the order the array holds rather than sorting it — `docs/decisions.md` §Equality is deep restores
|
||||||
the array, not a set — and opens each spelling once over the longest run of adjacent inline nodes
|
the array, not a set — and opens each spelling once over the longest run of adjacent inline nodes
|
||||||
carrying an identical mark, attributes included, at that depth: `attrs: {}` differs from no `attrs`,
|
carrying an identical mark, attributes included, at that depth, an emphasis or link spelling also
|
||||||
and a directive spells it `{attrs=empty}`. A run breaks at every node the emitter carries, so no
|
spanning a hard break between two of them: `attrs: {}` differs from no `attrs`, and a directive
|
||||||
emitted carry sits inside a mark spelling.
|
spells it `{attrs=empty}`. A run breaks at every node the emitter carries, so no emitted carry sits
|
||||||
|
inside a mark spelling.
|
||||||
|
|
||||||
An inline node whose marks no nesting spells — a hard break holding any mark, a mark type not listed
|
An inline node whose marks no nesting spells — a hard break holding any mark, a mark type not listed
|
||||||
here, an attrs key its spelling does not list, a value that is not the spelling's type, an attribute
|
here, an attrs key its spelling does not list, a value that is not the spelling's type, an attribute
|
||||||
|
|||||||
@@ -713,6 +713,17 @@ test('spells the directive marks around the longest run they cover', () => {
|
|||||||
assert.equal(emitted(marked('a', underline), { type: 'hardBreak' }, marked('b', underline)), '!adf:underline[a]\\\n!adf:underline[b]\n')
|
assert.equal(emitted(marked('a', underline), { type: 'hardBreak' }, marked('b', underline)), '!adf:underline[a]\\\n!adf:underline[b]\n')
|
||||||
})
|
})
|
||||||
|
|
||||||
|
test('spells a mark run across the hard break between two nodes holding the mark', () => {
|
||||||
|
const em: AdfMark = { type: 'em' }
|
||||||
|
const link: AdfMark = { attrs: { href: '/u' }, type: 'link' }
|
||||||
|
const marked = (text: string, ...marks: AdfMark[]): AdfNode => ({ marks, text, type: 'text' })
|
||||||
|
const hardBreak: AdfNode = { type: 'hardBreak' }
|
||||||
|
assert.equal(readsBack(document(paragraph(marked('a', em), hardBreak, marked('b', em)))), '_a\\\nb_\n')
|
||||||
|
assert.equal(readsBack(document(paragraph(marked('a', link), hardBreak, marked('b', link)))), '[a\\\nb](/u)\n')
|
||||||
|
assert.equal(readsBack(document(paragraph(marked('a', em, link), hardBreak, marked('b', em)))), '_[a](/u)\\\nb_\n')
|
||||||
|
assert.equal(readsBack(document(paragraph(marked('a', em), hardBreak, hardBreak, marked('b', em)))), '_a_\\\n\\\n_b_\n')
|
||||||
|
})
|
||||||
|
|
||||||
test('carries a hard break holding marks, which Atlassian\'s schema gives it none of', () => {
|
test('carries a hard break holding marks, which Atlassian\'s schema gives it none of', () => {
|
||||||
const link: AdfMark = { attrs: { href: 'https://example.com/' }, type: 'link' }
|
const link: AdfMark = { attrs: { href: 'https://example.com/' }, type: 'link' }
|
||||||
assert.equal(
|
assert.equal(
|
||||||
|
|||||||
@@ -196,17 +196,30 @@ function inlineRuns(nodes: readonly AdfNode[], depth: number, firstIndex: number
|
|||||||
const index = firstIndex + offset
|
const index = firstIndex + offset
|
||||||
// `depth` indexes each node's marks, outermost first; a carried node spells its marks inside the carry.
|
// `depth` indexes each node's marks, outermost first; a carried node spells its marks inside the carry.
|
||||||
const mark = carries(node, carried, index) ? undefined : nodeMarks(node)[depth]
|
const mark = carries(node, carried, index) ? undefined : nodeMarks(node)[depth]
|
||||||
|
const previous = runs[runs.length - 1]
|
||||||
|
if (mark === undefined && previous?.kind === 'marked' && joinsRun(node, index, nodes[offset + 1], previous.mark, depth, carried)) {
|
||||||
|
previous.nodes.push(node)
|
||||||
|
continue
|
||||||
|
}
|
||||||
if (mark === undefined) {
|
if (mark === undefined) {
|
||||||
runs.push({ index, kind: 'plain', node })
|
runs.push({ index, kind: 'plain', node })
|
||||||
continue
|
continue
|
||||||
}
|
}
|
||||||
const previous = runs[runs.length - 1]
|
|
||||||
if (previous?.kind === 'marked' && identicalMark(previous.mark, mark)) previous.nodes.push(node)
|
if (previous?.kind === 'marked' && identicalMark(previous.mark, mark)) previous.nodes.push(node)
|
||||||
else runs.push({ index, kind: 'marked', mark, nodes: [node] })
|
else runs.push({ index, kind: 'marked', mark, nodes: [node] })
|
||||||
}
|
}
|
||||||
return runs
|
return runs
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// The reader marks no hard break, so one between two nodes holding an emphasis or link mark reads back inside its spelling.
|
||||||
|
function joinsRun(node: AdfNode, index: number, next: AdfNode | undefined, mark: AdfMark, depth: number, carried: ReadonlySet<number>): boolean {
|
||||||
|
if (node.type !== 'hardBreak' || carries(node, carried, index) || next === undefined || carries(next, carried, index + 1)) return false
|
||||||
|
const kind = markSpelling(mark.type)?.kind
|
||||||
|
if (kind !== 'emphasis' && kind !== 'link') return false
|
||||||
|
const nextMark = nodeMarks(next)[depth]
|
||||||
|
return nextMark !== undefined && identicalMark(nextMark, mark)
|
||||||
|
}
|
||||||
|
|
||||||
function takesTextBreak(previous: InlineRun | undefined, run: InlineRun, carried: ReadonlySet<number>): boolean {
|
function takesTextBreak(previous: InlineRun | undefined, run: InlineRun, carried: ReadonlySet<number>): boolean {
|
||||||
if (previous?.kind !== 'plain' || run.kind !== 'plain') return false
|
if (previous?.kind !== 'plain' || run.kind !== 'plain') return false
|
||||||
if (carries(previous.node, carried, previous.index) || carries(run.node, carried, run.index)) return false
|
if (carries(previous.node, carried, previous.index) || carries(run.node, carried, run.index)) return false
|
||||||
|
|||||||
@@ -260,9 +260,12 @@ function directivePiece(scan: Scan, span: DirectiveSpan, index: number): Result<
|
|||||||
}
|
}
|
||||||
|
|
||||||
function directiveMarkPiece(scan: Scan, name: string, mark: AdfMark, slot: SlotContent | undefined, index: number): Result<Piece> {
|
function directiveMarkPiece(scan: Scan, name: string, mark: AdfMark, slot: SlotContent | undefined, index: number): Result<Piece> {
|
||||||
if (slot?.nodes.some(holdsOwnMarks) === true) return failure('unsupported-node-shape', ownMarksInMark, scan.path)
|
if (slot === undefined || slot.nodes.length === 0) {
|
||||||
if (slot === undefined || slot.nodes.every(takesNoMarks)) {
|
return failure('unsupported-node-shape', `the ${name} mark wraps the [content] it marks: this one wraps none`, scan.path)
|
||||||
return failure('unsupported-node-shape', `the ${name} mark wraps the [content] it marks: this one wraps nothing a mark rides`, scan.path)
|
}
|
||||||
|
if (slot.nodes.some(holdsOwnMarks)) return failure('unsupported-node-shape', ownMarksInMark, scan.path)
|
||||||
|
if (slot.nodes.every(takesNoMarks)) {
|
||||||
|
return failure('unsupported-node-shape', `the ${name} mark wraps the [content] it marks: this one wraps only hard breaks, which take no marks`, scan.path)
|
||||||
}
|
}
|
||||||
const refused = mark.type === 'link' ? refuseLinkDirective(scan, mark, slot.nodes, index) : undefined
|
const refused = mark.type === 'link' ? refuseLinkDirective(scan, mark, slot.nodes, index) : undefined
|
||||||
if (refused !== undefined) return refused
|
if (refused !== undefined) return refused
|
||||||
|
|||||||
@@ -1181,11 +1181,12 @@ test('names the link a directive link wraps, no link holding another', () => {
|
|||||||
})
|
})
|
||||||
|
|
||||||
test('names the directive mark left without the content it wraps', () => {
|
test('names the directive mark left without the content it wraps', () => {
|
||||||
const named = 'unsupported-node-shape: the underline mark wraps the [content] it marks: this one wraps nothing a mark rides'
|
const named = 'unsupported-node-shape: the underline mark wraps the [content] it marks: this one wraps none'
|
||||||
assert.equal(content(losslessMarkdownToAdf('!adf:underline[]\n')), named)
|
assert.equal(content(losslessMarkdownToAdf('!adf:underline[]\n')), named)
|
||||||
assert.equal(content(losslessMarkdownToAdf('!adf:underline{}\n')), named)
|
assert.equal(content(losslessMarkdownToAdf('!adf:underline{}\n')), named)
|
||||||
assert.equal(content(losslessMarkdownToAdf('!adf:underline[!adf:hardBreak{}]\n')), named)
|
const breaks = 'the [content] it marks: this one wraps only hard breaks, which take no marks'
|
||||||
assert.equal(content(losslessMarkdownToAdf('!adf:link[!adf:hardBreak{}]{href="/u" title=t}\n')), named.replace('underline', 'link'))
|
assert.equal(content(losslessMarkdownToAdf('!adf:underline[!adf:hardBreak{}]\n')), `unsupported-node-shape: the underline mark wraps ${breaks}`)
|
||||||
|
assert.equal(content(losslessMarkdownToAdf('!adf:link[!adf:hardBreak{}]{href="/u" title=t}\n')), `unsupported-node-shape: the link mark wraps ${breaks}`)
|
||||||
})
|
})
|
||||||
|
|
||||||
test('reads the text break only between two text nodes CommonMark joins, building no node', () => {
|
test('reads the text break only between two text nodes CommonMark joins, building no node', () => {
|
||||||
|
|||||||
@@ -309,7 +309,7 @@ test('breaks a line at a newline and trims whitespace at every edge CommonMark s
|
|||||||
assert.equal(portable(paragraph(text(' \n a \n b\n'))), 'a\\\nb\n')
|
assert.equal(portable(paragraph(text(' \n a \n b\n'))), 'a\\\nb\n')
|
||||||
assert.equal(portable(paragraph({ type: 'hardBreak' }, text('a'), { attrs: { text: '\n' }, type: 'hardBreak' }, text('b'), { type: 'hardBreak' })), 'a\\\nb\n')
|
assert.equal(portable(paragraph({ type: 'hardBreak' }, text('a'), { attrs: { text: '\n' }, type: 'hardBreak' }, text('b'), { type: 'hardBreak' })), 'a\\\nb\n')
|
||||||
assert.equal(portable(paragraph(text('a'), text(' b ', strong), text('c'))), 'a **b** c\n')
|
assert.equal(portable(paragraph(text('a'), text(' b ', strong), text('c'))), 'a **b** c\n')
|
||||||
assert.equal(portable(paragraph(text(' '), text('b', strong), text(' \n'), text('c', strong), text(' '))), '**b**\\\n**c**\n')
|
assert.equal(portable(paragraph(text(' '), text('b', strong), text(' \n'), text('c', strong), text(' '))), '**b\\\nc**\n')
|
||||||
assert.equal(portable(paragraph(text('a'), text(' b ', em, strong), text(' ', em), text('c', em))), 'a _**b** c_\n')
|
assert.equal(portable(paragraph(text('a'), text(' b ', em, strong), text(' ', em), text('c', em))), 'a _**b** c_\n')
|
||||||
assert.equal(portable(paragraph(text(' x ', code))), '` x `\n')
|
assert.equal(portable(paragraph(text(' x ', code))), '` x `\n')
|
||||||
assert.equal(portable(node('heading', { level: 1 }, text(' h\ni '))), '# h i\n')
|
assert.equal(portable(node('heading', { level: 1 }, text(' h\ni '))), '# h i\n')
|
||||||
|
|||||||
Reference in New Issue
Block a user