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

Answer prose round 1: 0 🔴, 13 🟡 (0 misread); define markup characters once, state when empty values and carriage returns ride, and fix the comments and test names

This commit is contained in:
2026-11-17 02:12:22 +01:00
committed by Lillem4n
parent 5facc0fc5d
commit de091a1c4e
8 changed files with 79 additions and 68 deletions
+20 -17
View File
@@ -28,13 +28,14 @@ A node rides the carry when it, one of its attributes or one of its marks has no
also rides when it holds a block or inline node that rides, except that a node that rides inside a
paragraph stands on its own there, in the paragraph's text. A block that rides inside a list item or
a table cell makes the list or the table ride instead, since wiki markup can't hold a block macro
there. A `{quote}` holding another `{quote}` at any depth rides, as does a `panel` holding another
`panel`, since a macro can't nest in its own kind. Any `localId` rides, since `docs/decisions.md`
there. A `blockquote` written as `{quote}` that holds another at any depth rides, as does a `panel`
holding another `panel` at any depth, since a macro can't nest in its own kind. Any `localId` rides, since `docs/decisions.md`
§Ids stay site-local keeps ids in attributes.
## Blocks
Blocks are parted by one blank line. A document whose `content` is an empty array is the empty
Below, a markup character is a backslash, a bracket, a brace or `|`. Blocks are parted by one blank
line. A document whose `content` is an empty array is the empty
string.
| ADF | Wiki markup | Reader |
@@ -44,7 +45,7 @@ string.
| `bulletList`, `orderedList` of `order` 1, its items each a paragraph then lists | `* ` and `# `, one more character per level, nested lists mixed as `#* ` and `*# ` | the same, and `- ` items as `* `; an `orderedList` reads `order` 1 |
| `codeBlock` holding one text node, of `language` `""` or a name below in lowercase | `{code:<language>}`, a line feed, the text, a line feed, `{code}`; for `""`, `{noformat}`, the text, `{noformat}` the same way | the same, reading a `{code:<language>}` name in lowercase and `{noformat}` as `language` `""`; `{code}` reads `java`; `title`, `borderStyle` and the other panel parameters drop |
| `heading` | `h1. ` to `h6. ` by `level` | the same |
| `mediaSingle` of `layout` `center`, holding one external `media` and no caption | `!<url>!`, or `!<url>\|alt=<alt>!` where `alt` holds none of `!`, `\|`, `,`, a backslash, a bracket, a brace or a line feed, and doesn't start or end with whitespace; a `url` holding whitespace or one of `!`, `\|`, a backslash, a bracket or a brace rides the carry | the same, reading `layout` `center`; `thumbnail`, `align` and the other parameters drop |
| `mediaSingle` of `layout` `center`, holding one external `media` and no caption | `!<url>!`, or `!<url>\|alt=<alt>!` where `alt` isn't empty, holds no markup character, `!`, `,`, line feed or carriage return, and doesn't start or end with whitespace; a `url` that is empty or holds whitespace, `!` or a markup character rides the carry | the same, reading `layout` `center`; `thumbnail`, `align` and the other parameters drop |
| `panel` of `panelType` `error`, `info`, `note`, `success` or `warning` | `{panel:bgColor=<colour>}`, a line feed, its blocks, a line feed, `{panel}`, the colour being `#ffebe6` for `error`, `#deebff` for `info`, `#eae6ff` for `note`, `#e3fcef` for `success` and `#fffae6` for `warning` | the same; a `title` parameter reads as the panel's first paragraph in `strong`; `{panel}` and any `bgColor` the five spellings leave out read as `info`, colours compared without case; the other parameters drop |
| `paragraph` holding content | its inline content | the same; a line feed in it reads as a `hardBreak`, as Jira renders it |
| `rule` | `----` | the same |
@@ -64,40 +65,42 @@ a `width`, a merged cell and a colour.
| ADF | Wiki markup | Reader |
| --- | --- | --- |
| `hardBreak` | `\\` | the same |
| `mention` holding `id` and `accessLevel` `""`, and no other attribute, the `id` holding no whitespace, backslash, bracket, brace or `\|` | `[~accountid:<id>]` | the same, reading `accessLevel` `""`; `[~name]` reads as text, since Jira Cloud names a user by account id |
| `mention` holding `id` and `accessLevel` `""`, and no other attribute, the `id` not empty and holding no whitespace or markup character | `[~accountid:<id>]` | the same, reading `accessLevel` `""`; `[~name]` reads as text, since Jira Cloud names a user by account id |
| `text` | its text, escaped as below | `\\` reads as a `hardBreak` before `\X` reads `X`; a bare `http://` or `https://` address reads as a `link` |
| any other inline node | the carry | `{adf:display=inline}` reads its nodes |
A character takes a backslash where wiki markup would read it as markup:
A character takes a backslash where wiki markup would read it as markup. Here a line's edge counts
as whitespace, and a node's edge inside the line as punctuation:
- `[`, `]`, `{`, `}` and `|`, always.
- `*`, `+`, `-`, `^`, `_` and `~`, unless a letter or digit stands on both sides, or whitespace
does. A line's edge counts as whitespace, and a node's edge inside the line as punctuation.
does.
- `?` before another `?`, and `!` before anything but whitespace.
- The first character of a smiley in the help's list, where no letter or digit follows the smiley,
or where the node's edge cuts it inside the line.
- The first character of a smiley listed under What only the reader reads, where no letter or digit
follows the smiley, or where the node's edge cuts it inside the line.
- At a line's start, `#`, `*` and `-`, and the `h` of `h1.` to `h6.` and the `b` of `bq.`, in any
case.
A text rides the carry where no backslash protects it: where it holds a backslash, a line feed, or
`http://` or `https://`, which Jira would link, or where whitespace starts or ends the line. So does a
text whose marks are those of the text before it, which the reader would join, and a `hardBreak` or
`mention` holding a mark.
No backslash protects a backslash, a line feed, a carriage return, or `http://` or `https://` in any
case, which Jira would link, so a text holding one rides the carry. So does a text that starts or
ends its line with whitespace, and a text whose marks are those of the text before it, which the
reader would join. A `hardBreak` or `mention` holding a mark rides too.
## Marks
| ADF | Wiki markup | Reader |
| --- | --- | --- |
| `code`, `em`, `strike`, `strong`, `underline` | `{{x}}`, `_x_`, `-x-`, `*x*`, `+x+` | the same; `??x??` reads `em` |
| `link` holding `href` | `[<text>\|<href>]`, with `\|<title>` after the `href` where it holds a `title`; `[<href>]` where the text is the `href`, the link marks neither neighbour and holds no `title`, and the `href` doesn't start with `~`; an `href` holding whitespace, a backslash, a bracket, a brace or `\|`, or a `title` holding a line feed, a backslash, a bracket, a brace or `\|` or starting or ending with whitespace, rides the carry | the same; `[#anchor]` and `[^name.ext]` read as `href` `#anchor` and `^name.ext` |
| `link` holding `href` | `[<text>\|<href>]`, with `\|<title>` after the `href` where it holds a `title`; `[<href>]` where the link is the text's last mark, the text is the `href`, the link marks neither neighbour and holds no `title`, and the `href` doesn't start with `~`; an `href` that is empty or holds whitespace or a markup character rides the carry, as does a `title` that is empty, holds a markup character, a line feed or a carriage return, or starts or ends with whitespace | the same; `[#anchor]` and `[^name.ext]` read as `href` `#anchor` and `^name.ext` |
| `subsup` | `^x^` for `sup`, `~x~` for `sub` | the same |
| `textColor` | `{color:<hex>}x{color}` | the same; a CSS colour name reads as its hex code, so `red` as `#ff0000` |
| any other mark | the carry around the marked run | `{adf:display=inline}` reads its run |
Marks nest in the order the node's array holds them, outermost first, and a run of nodes sharing
their outermost mark shares its delimiters. A mark's character delimiters sit beside whitespace,
punctuation or the line's edge, and the run's first and last characters are not whitespace. A run
where either fails rides the carry whole, as does a node holding two marks of one type.
their outermost mark shares its delimiters. The delimiters of `code`, `em`, `strike`, `strong`,
`subsup` and `underline` each need whitespace, punctuation or the line's edge outside them, and no
whitespace inside them. A run where one fails rides the carry whole, as does a node holding two marks
of one type.
## The lossy writer
+1 -1
View File
@@ -11,7 +11,7 @@ import { parseJsonText } from '../json-text.ts'
// JSON `carriedNesting` found within the levels its position leaves, the one value `carriedNode` reads.
export type BoundedJson = { readonly bounded: JsonValue }
// `carried` is the node, or the run of nodes, the carry holds; `spelled` is it as the carry holds it, `type` dropped where the format names it apart; `levels` the nesting its position leaves.
// `carried`: the node, or the run of nodes, being carried; `spelled`: the JSON written for `carried`, its `type` dropped where the format names it apart; `levels` the nesting its position leaves.
export function carriedJson(carried: AdfNode | readonly AdfNode[], spelled: object, spelling: JsonSpelling, path: ConvertErrorPath, levels: number): Result<{ headroom: number; json: string }> {
const headroom = levels - nestingDepth(carried)
if (!isJsonValue(spelled) || headroom < 0) return faulted(nestedPast(levels), path)
+1 -2
View File
@@ -3,13 +3,12 @@ import { carriedJson } from '../adf/carried-json.ts'
import { largestNesting } from '../nesting.ts'
import { success, type ConvertErrorPath, type Result } from '../result.ts'
// spec/wiki.md, The carry. Only the document's own blocks ride, so a block carry has every level.
// spec/wiki.md, The carry.
export function blockCarry(node: AdfNode, path: ConvertErrorPath): Result<string> {
const json = carriedJson(node, node, 'compact', path, largestNesting)
return json.ok ? success(`{adf:display=block}\n${closingMacroEscaped(json.value.json)}\n{adf}`) : json
}
// One node is carried as its JSON, a run of several as an array.
export function inlineCarry(nodes: readonly AdfNode[], path: ConvertErrorPath): Result<string> {
const carried = nodes.length === 1 && nodes[0] !== undefined ? nodes[0] : nodes
const json = carriedJson(carried, carried, 'compact', path, largestNesting)
+35 -40
View File
@@ -124,11 +124,6 @@ test('writes a centred external image, with its alt where it holds one', () => {
assert.equal(wiki(image({ alt: 'A', type: 'external', url: 'https://example.com/a.png' })), '!https://example.com/a.png|alt=A!')
})
test('writes a panel of each of the five types with its colour', () => {
assert.equal(wiki(panel('info', paragraph(text('Note this')))), '{panel:bgColor=#deebff}\nNote this\n{panel}')
assert.equal(wiki(panel('error', paragraph(text('x')))), '{panel:bgColor=#ffebe6}\nx\n{panel}')
})
test('writes a rule as four dashes', () => {
assert.equal(wiki({ type: 'rule' }), '----')
})
@@ -151,7 +146,7 @@ test('carries a paragraph holding no content or only whitespace outside a table
assert.equal(wiki(paragraph(text(' '))), block('{"content":[{"text":" ","type":"text"}],"type":"paragraph"}'))
})
test('carries a block holding an attribute value no spelling stands for', () => {
test('carries a block wiki markup cannot spell', () => {
assert.equal(wiki({ attrs: { order: 3 }, content: [item(paragraph(text('a')))], type: 'orderedList' }), block('{"attrs":{"order":3},"content":[{"content":[{"content":[{"text":"a","type":"text"}],"type":"paragraph"}],"type":"listItem"}],"type":"orderedList"}'))
assert.equal(wiki({ attrs: { localId: 'p1' }, content: [text('a')], type: 'paragraph' }), block('{"attrs":{"localId":"p1"},"content":[{"text":"a","type":"text"}],"type":"paragraph"}'))
assert.equal(wiki(code('foo', 'x')), block('{"attrs":{"language":"foo"},"content":[{"text":"x","type":"text"}],"type":"codeBlock"}'))
@@ -176,7 +171,7 @@ test('carries a list item holding two lists of one kind in a row, which would re
assert.equal(wiki(list('bulletList', item(paragraph(text('a')), nested, nested))).startsWith('{adf:display=block}'), true)
})
test('carries a quote macro holding another, and a panel holding another, since the macros cannot nest', () => {
test('carries a macro nested in its own kind, and writes one nested in the other kind or as bq.', () => {
assert.equal(wiki(quote(paragraph(text('a')), quote(paragraph(text('b')), paragraph(text('c'))))).startsWith('{adf:display=block}'), true)
assert.equal(wiki(panel('info', panel('note', paragraph(text('a'))))).startsWith('{adf:display=block}'), true)
assert.equal(wiki(quote(paragraph(text('a')), quote(paragraph(text('b'))))), '{quote}\na\n\nbq. b\n{quote}')
@@ -262,7 +257,7 @@ test('carries the run of nodes under a mark with no spelling as an array', () =>
assert.equal(wiki(paragraph(text('a', background), text('b', background, { type: 'strong' }))), inline('[{"marks":[{"attrs":{"color":"#ffff00"},"type":"backgroundColor"}],"text":"a","type":"text"},{"marks":[{"attrs":{"color":"#ffff00"},"type":"backgroundColor"},{"type":"strong"}],"text":"b","type":"text"}]'))
})
test('carries a mark holding an attribute value no spelling stands for', () => {
test('carries a mark no spelling stands for, and two marks of one type', () => {
assert.equal(marked({ attrs: {}, type: 'strong' }), `a ${inline('{"marks":[{"attrs":{},"type":"strong"}],"text":"b","type":"text"}')} c`)
assert.equal(marked({ attrs: { color: 'red' }, type: 'textColor' }).includes('{adf:display=inline}'), true)
assert.equal(marked({ attrs: { type: 'mid' }, type: 'subsup' }).includes('{adf:display=inline}'), true)
@@ -289,7 +284,7 @@ test('refuses what every writer refuses before writing', () => {
assert.equal(refusal(adfToLosslessJiraWiki(JSON.parse('{"type":"doc"}'))), 'not-an-adf-document at /')
})
test('carries a heading of no level 1 to 6, or of no content', () => {
test('carries a heading whose level is outside 1 to 6, or that holds no content', () => {
assert.equal(wiki({ attrs: { level: 7 }, content: [text('a')], type: 'heading' }), block('{"attrs":{"level":7},"content":[{"text":"a","type":"text"}],"type":"heading"}'))
assert.equal(wiki({ attrs: { level: 1 }, type: 'heading' }), block('{"attrs":{"level":1},"type":"heading"}'))
})
@@ -308,7 +303,7 @@ test('carries a code mark holding attributes', () => {
assert.equal(marked({ attrs: { a: 1 }, type: 'code' }), `a ${inline('{"marks":[{"attrs":{"a":1},"type":"code"}],"text":"b","type":"text"}')} c`)
})
test('writes a link text equal to its href with its text where the link marks a neighbour too', () => {
test('writes a link text equal to its href as [text|href] where the link also marks a neighbour', () => {
const link = { attrs: { href: 'mailto:a@example.com' }, type: 'link' }
assert.equal(wiki(paragraph(text('mailto:a@example.com', link), text('b', { type: 'strong' }, link))), '[mailto:a@example.com|mailto:a@example.com]*[b|mailto:a@example.com]*')
assert.equal(wiki(paragraph(text('b', { type: 'strong' }, link), text('mailto:a@example.com', link))), '*[b|mailto:a@example.com]*[mailto:a@example.com|mailto:a@example.com]')
@@ -344,36 +339,36 @@ for (const [panelType, colour] of [['error', '#ffebe6'], ['info', '#deebff'], ['
const external = { type: 'external', url: 'https://example.com/a.png' }
const riddenBlocks: [string, AdfNode][] = [
['an image whose mediaSingle holds no content', { attrs: { layout: 'center' }, type: 'mediaSingle' }],
['an image whose mediaSingle holds no media', { attrs: { layout: 'center' }, content: [paragraph(text('a'))], type: 'mediaSingle' }],
['an image whose mediaSingle holds its caption first', { attrs: { layout: 'center' }, content: [{ content: [text('c')], type: 'caption' }, { attrs: external, type: 'media' }], type: 'mediaSingle' }],
['an image whose mediaSingle holds two media', { attrs: { layout: 'center' }, content: [{ attrs: external, type: 'media' }, { attrs: external, type: 'media' }], type: 'mediaSingle' }],
['an image whose media holds a width', image({ ...external, width: 10 })],
['an image of a stored file with a URL', image({ type: 'file', url: 'https://example.com/a.png' })],
['an image whose URL is no string', image({ type: 'external', url: 5 })],
['an image whose alt is no string', image({ ...external, alt: 5 })],
['an image whose alt ends in whitespace', image({ ...external, alt: 'A cat ' })],
['a media group of layout center', { attrs: { layout: 'center' }, content: [{ attrs: external, type: 'media' }], type: 'mediaGroup' }],
['a code block whose language is no string', { attrs: { language: 5 }, content: [text('x')], type: 'codeBlock' }],
['a blockquote holding a panel that holds a quote', quote(panel('info', quote(paragraph(text('a')), paragraph(text('b')))))],
['a blockquote holding no content', { type: 'blockquote' }],
['a code block holding another attribute', { attrs: { language: 'java', title: 'a' }, content: [text('x')], type: 'codeBlock' }],
['a code block of a marked text', { attrs: { language: 'java' }, content: [text('x', { type: 'strong' })], type: 'codeBlock' }],
['a code block of no content', { attrs: { language: 'java' }, type: 'codeBlock' }],
['a code block of two texts', { attrs: { language: 'java' }, content: [text('x'), text('y', { type: 'strong' })], type: 'codeBlock' }],
['a code block of a marked text', { attrs: { language: 'java' }, content: [text('x', { type: 'strong' })], type: 'codeBlock' }],
['a code block holding another attribute', { attrs: { language: 'java', title: 'a' }, content: [text('x')], type: 'codeBlock' }],
['a blockquote holding no content', { type: 'blockquote' }],
['a list holding a paragraph', { content: [paragraph(text('a'))], type: 'bulletList' }],
['a code block whose language is no string', { attrs: { language: 5 }, content: [text('x')], type: 'codeBlock' }],
['a list holding a list item and a paragraph', { content: [item(paragraph(text('a'))), paragraph(text('b'))], type: 'bulletList' }],
['a blockquote holding a panel that holds a quote', quote(panel('info', quote(paragraph(text('a')), paragraph(text('b')))))],
['a list holding a paragraph', { content: [paragraph(text('a'))], type: 'bulletList' }],
['a list item holding a localId', list('bulletList', { attrs: { localId: 'i1' }, content: [paragraph(text('a'))], type: 'listItem' })],
['a list item opening with a list', list('bulletList', item(list('bulletList', item(paragraph(text('a'))))))],
['a panel whose panelType is an array', { attrs: { panelType: ['info'] }, content: [paragraph(text('a'))], type: 'panel' }],
['a media group of layout center', { attrs: { layout: 'center' }, content: [{ attrs: external, type: 'media' }], type: 'mediaGroup' }],
['a panel holding another attribute', { attrs: { panelIcon: ':x:', panelType: 'info' }, content: [paragraph(text('a'))], type: 'panel' }],
['a panel whose panelType is an array', { attrs: { panelType: ['info'] }, content: [paragraph(text('a'))], type: 'panel' }],
['a paragraph of whitespace texts', paragraph(text(' '), text(' ', { type: 'strong' }))],
['a table cell holding a code block', table(plainTable, [{ content: [code('java', 'x')], type: 'tableCell' }])],
['a table holding a paragraph', { attrs: plainTable, content: [paragraph(text('a'))], type: 'table' }],
['a table holding a row and a paragraph', { attrs: plainTable, content: [{ content: [cell('tableCell', text('a'))], type: 'tableRow' }, paragraph(text('b'))], type: 'table' }],
['a table cell holding a code block', table(plainTable, [{ content: [code('java', 'x')], type: 'tableCell' }])],
['a table row holding a cell and a paragraph', { attrs: plainTable, content: [{ content: [cell('tableCell', text('a')), paragraph(text('b'))], type: 'tableRow' }], type: 'table' }],
['a table row holding a localId', { attrs: plainTable, content: [{ attrs: { localId: 'r1' }, content: [cell('tableCell', text('a'))], type: 'tableRow' }], type: 'table' }],
['a table row holding a paragraph', { attrs: plainTable, content: [{ content: [paragraph(text('a'))], type: 'tableRow' }], type: 'table' }],
['a table row holding a cell and a paragraph', { attrs: plainTable, content: [{ content: [cell('tableCell', text('a')), paragraph(text('b'))], type: 'tableRow' }], type: 'table' }],
['a paragraph of whitespace texts', paragraph(text(' '), text(' ', { type: 'strong' }))],
['an image of a stored file with a URL', image({ type: 'file', url: 'https://example.com/a.png' })],
['an image whose URL is no string', image({ type: 'external', url: 5 })],
['an image whose alt ends in whitespace', image({ ...external, alt: 'A cat ' })],
['an image whose alt is no string', image({ ...external, alt: 5 })],
['an image whose media holds a width', image({ ...external, width: 10 })],
['an image whose mediaSingle holds its caption first', { attrs: { layout: 'center' }, content: [{ content: [text('c')], type: 'caption' }, { attrs: external, type: 'media' }], type: 'mediaSingle' }],
['an image whose mediaSingle holds no content', { attrs: { layout: 'center' }, type: 'mediaSingle' }],
['an image whose mediaSingle holds no media', { attrs: { layout: 'center' }, content: [paragraph(text('a'))], type: 'mediaSingle' }],
['an image whose mediaSingle holds two media', { attrs: { layout: 'center' }, content: [{ attrs: external, type: 'media' }, { attrs: external, type: 'media' }], type: 'mediaSingle' }],
]
for (const [name, node] of riddenBlocks) {
test(`carries ${name}`, () => {
@@ -397,7 +392,7 @@ test('writes a blockquote of one block other than a paragraph as a quote macro',
assert.equal(wiki(quote(code('java', 'x'))), '{quote}\n{code:java}\nx\n{code}\n{quote}')
})
test('writes a list inside a quote macro from its first marker', () => {
test('writes a list inside a quote macro with a top-level list\'s markers', () => {
assert.equal(wiki(quote(list('bulletList', item(paragraph(text('a')))), paragraph(text('b')))), '{quote}\n* a\n\nb\n{quote}')
})
@@ -442,7 +437,7 @@ test('writes a link and a colour mid-word, whose delimiters read anywhere', () =
assert.equal(wiki(paragraph(text('a'), text('b', { attrs: { color: '#ff0000' }, type: 'textColor' }), text('c'))), 'a{color:#ff0000}b{color}c')
})
test('carries a code or subsup run mid-word, whose delimiters read only beside punctuation', () => {
test('carries a code or subsup run mid-word, whose delimiters read only beside whitespace, punctuation or the line\'s edge', () => {
assert.equal(wiki(paragraph(text('a '), text('b', { type: 'code' }), text('c'))).includes('{adf:display=inline}'), true)
assert.equal(wiki(paragraph(text('a '), text('b', { attrs: { type: 'sup' }, type: 'subsup' }), text('c'))).includes('{adf:display=inline}'), true)
})
@@ -456,18 +451,18 @@ test('writes a link whose href starts with ~ with its text, since [~x] names a u
})
const riddenMarks: [string, AdfMark][] = [
['a colour followed by more', { attrs: { color: '#ff0000x' }, type: 'textColor' }],
['a colour led by more', { attrs: { color: 'x#ff0000' }, type: 'textColor' }],
['a colour held in an array', { attrs: { color: ['#ff0000'] }, type: 'textColor' }],
['a colour holding another attribute', { attrs: { color: '#ff0000', x: 1 }, type: 'textColor' }],
['a colour of a hex code then more', { attrs: { color: '#ff0000x' }, type: 'textColor' }],
['a colour of more then a hex code', { attrs: { color: 'x#ff0000' }, type: 'textColor' }],
['a link holding another attribute', { attrs: { href: 'https://example.com', x: 1 }, type: 'link' }],
['a link whose href is no string', { attrs: { href: 5 }, type: 'link' }],
['a link whose title ends in whitespace', { attrs: { href: 'https://example.com', title: 'T ' }, type: 'link' }],
['a link whose title is no string', { attrs: { href: 'https://example.com', title: 5 }, type: 'link' }],
['a mark of another type holding an href', { attrs: { href: 'https://example.com' }, type: 'fancyLink' }],
['a mark of type __proto__', { type: '__proto__' }],
['a mark of type toString', { type: 'toString' }],
['a subsup holding another attribute', { attrs: { type: 'sub', x: 1 }, type: 'subsup' }],
['a mark of another type holding an href', { attrs: { href: 'https://example.com' }, type: 'fancyLink' }],
['a link whose href is no string', { attrs: { href: 5 }, type: 'link' }],
['a link holding another attribute', { attrs: { href: 'https://example.com', x: 1 }, type: 'link' }],
['a link whose title is no string', { attrs: { href: 'https://example.com', title: 5 }, type: 'link' }],
['a link whose title ends in whitespace', { attrs: { href: 'https://example.com', title: 'T ' }, type: 'link' }],
]
for (const [name, mark] of riddenMarks) {
test(`carries the run of ${name}`, () => {
@@ -476,9 +471,9 @@ for (const [name, mark] of riddenMarks) {
}
const riddenInlines: [string, AdfNode][] = [
['a node of another type holding an id and accessLevel ""', { attrs: { accessLevel: '', id: '5b10' }, type: 'unknownInline' }],
['a mention of another accessLevel', { attrs: { accessLevel: 'CONTAINER', id: '5b10' }, type: 'mention' }],
['a mention whose id is no string', { attrs: { accessLevel: '', id: 5 }, type: 'mention' }],
['a node of another type holding an id and accessLevel ""', { attrs: { accessLevel: '', id: '5b10' }, type: 'unknownInline' }],
]
for (const [name, node] of riddenInlines) {
test(`carries ${name}`, () => {
+2 -1
View File
@@ -21,7 +21,7 @@ export function adfToLosslessJiraWiki(document: AdfDocument): Result<string> {
})
}
// Every block a spelled block holds is spelled too, so only the document's own blocks ride. A stack rather than recursion (docs/decisions.md §Nothing recurses unbounded).
// Every block a spelled block holds is spelled too, so only the document's own blocks ride.
function writeWiki(content: readonly AdfNode[]): Result<string> {
const found = spelledBlocks(content)
if (!found.ok) return found
@@ -39,6 +39,7 @@ function writeWiki(content: readonly AdfNode[]): Result<string> {
return joinedWithin(pieces)
}
// A stack rather than recursion (docs/decisions.md §Nothing recurses unbounded).
function writeSpelled(root: AdfNode, spelled: ReadonlyMap<AdfNode, Spelling>, pieces: string[]): void {
const pending: Pending[] = [{ node: root, prefix: '' }]
for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+1 -2
View File
@@ -21,7 +21,7 @@ const characterDelimiters: ReadonlyMap<string, string> = new Map([['em', '_'], [
const spellableUrl = /^[^\s[\]{}|\\]+$/
const spellableColour = /^#[0-9a-f]{6}$/i
// spec/wiki.md, Inline and Marks: the nodes, each run of marked nodes, and the carry around what wiki markup cannot spell.
// spec/wiki.md, Inline and Marks.
export function inlineLine(nodes: readonly AdfNode[], path: ConvertErrorPath): Result<Line> {
const atoms = nodes.map((node, index) => atom(node, nodes, index))
const groups = markedGroups(atoms)
@@ -88,7 +88,6 @@ function hrefSpelling(node: AdfNode, nodes: readonly AdfNode[], index: number):
return sharesLink(nodes[index - 1]) || sharesLink(nodes[index + 1]) ? undefined : `[${href}]`
}
// `undefined` where wiki markup has no spelling for the mark.
function markDelimiters(mark: AdfMark): Delimiters | undefined {
const attrs = nodeAttrs(mark)
const character = characterDelimiters.get(mark.type)
+2 -2
View File
@@ -6,7 +6,7 @@ import { inlineLine } from './inline-line.ts'
import { isHeadingLevel } from '../../adf/block-nodes.ts'
import { success, type ConvertErrorPath, type Result } from '../../result.ts'
// `blank`: a paragraph holding no content or only whitespace, which only a table cell holds, written as a space; `macros`: the `{quote}` and `{panel}` the block writes, which can't nest in their own kind; `text`: the block's spelling, where no container composes it.
// `blank`: a paragraph holding no content or only whitespace, which only a table cell holds; `macros`: the `{quote}` and `{panel}` the block writes, which can't nest in their own kind; `text`: the block's spelling, where no container composes it.
export type Spelling = { blank: boolean; macros: number; text: string | undefined }
type Step = { exit: boolean; node: AdfNode; path: ConvertErrorPath }
@@ -18,7 +18,7 @@ const lists = ['bulletList', 'orderedList']
const spellableAlt = /^[^\s!|,\\[\]{}](?:[^!|,\\[\]{}\r\n]*[^\s!|,\\[\]{}])?$/
const spellableImageUrl = /^[^\s!|\\[\]{}]+$/
// spec/wiki.md, Blocks: each block wiki markup spells, found after its children, since a block holding one that rides rides too. A stack rather than recursion (docs/decisions.md §Nothing recurses unbounded).
// spec/wiki.md, Blocks: each block wiki markup spells, found after its children, since a block rides where one it holds does. A stack rather than recursion (docs/decisions.md §Nothing recurses unbounded).
export function spelledBlocks(content: readonly AdfNode[]): Result<Map<AdfNode, Spelling>> {
const spelled = new Map<AdfNode, Spelling>()
const pending: Step[] = content.map((node, index) => ({ exit: false, node, path: ['content', index] })).reverse()
+17 -3
View File
@@ -6,12 +6,13 @@
`Bar = 0.1`
`Next ID = 198`
`Next ID = 199`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 198 | 0.4.0 | | | **Check on the Jira test site that Jira reads each backslash escape and each inline carry `adfToLosslessJiraWiki` writes as `spec/wiki.md` says, and respell or carry what it reads otherwise.** | 2 | 2 | 2 | 4 | 3 | 6 by 3, 11 by 2 | 4.4 |
| 193 | 0.4.0 | | owner | **Write ADF as Jira wiki markup, carrying in Jira's `{adf}` macro each node and mark wiki markup cannot spell.** | 3 | 1 | 2 | 4 | 7 | 11 by 4 | 0.4 |
| 194 | 0.4.0 | 193 | owner | **Write ADF as Jira wiki markup alone, dropping the form and keeping the content of what wiki markup cannot spell.** | 2 | 2 | 2 | 4 | 4 | 11 by 2 | 1.1 |
| 195 | 0.4.0 | 193 | owner | **Read Jira wiki markup into ADF, `{adf}` macros included, as `spec/wiki.md` says.** | 4 | 1 | 2 | 5 | 8 | 11 by 5 | 0.3 |
@@ -29,7 +30,7 @@
| 56 | 0.5.0 | | | **Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.** | 3 | 1 | 2 | 4 | 5 | code health by 5 | 7.8 |
| 118 | 0.5.0 | | | **Spell a portable link's title through `oneLine`.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 6.2 |
| 183 | 0.5.0 | | | **Answer developer-community topic 41858 once 0.4.0 is published.** | 1 | 1 | 1 | 1 | 1 | 3 by 2, 6.2 by 2 | 5.8 |
| 197 | 0.5.0 | | | **Write a heading holding a node wiki markup cannot spell as `h1.` to `h6.` with that node's inline carry, rather than carrying the whole heading.** | 2 | 1 | 1 | 2 | 3 | 6 by 3, 11 by 2 | 4.4 |
| 197 | 0.5.0 | 195 | | **Write a heading holding a node wiki markup cannot spell as `h1.` to `h6.` with that node's inline carry, rather than carrying the whole heading.** | 2 | 1 | 1 | 2 | 3 | 6 by 3, 11 by 2 | 4.4 |
| 82 | 0.5.0 | | | **Give the directive tests and fixtures random UUID v7 ids in place of `a-1`, `a`, `x` and `h`.** | 2 | 1 | 1 | 2 | 3 | code health by 1 | 3.9 |
| 178 | 0.5.0 | | owner | **Reach the comprehension floor: move the reasoning behind the emitter's fallback and escape loops into the code that runs them, so each reads on its own.** | 3 | 1 | 2 | 4 | 7 | code health by 8 | 3.7 |
| 58 | 0.5.0 | | | **Port `ci.sh`, `publish.sh`, `docker-runner.sh` and `mutation-tests/run.sh` to standalone Python scripts.** | 4 | 2 | 2 | 6 | 6 | code health by 3 | 2.6 |
@@ -47,6 +48,19 @@
## Details
### 198. Check on the Jira test site that Jira reads each backslash escape and each inline carry `adfToLosslessJiraWiki` writes as `spec/wiki.md` says, and respell or carry what it reads otherwise.
Item 193's reviews left three questions the 2026-11-17 live check in `docs/decisions.md` §Jira wiki markup spellings the help leaves open are a writer panel's picks doesn't answer:
- Whether Jira drops the backslash before `(`, `;`, `?`, `!`, `#`, and the `h` of `h1.` and the `b` of `bq.`. `(` is escaped often, as `(i)` is written `\(i)`.
- Whether an inline `{adf}` carry whose JSON holds `|` survives inside a table cell, and whether a carried `\\` survives anywhere.
- Smileys: the decision records that Jira keeps a backslash before `:` as text, so `:)` written as `\:)` shows a stray backslash in Jira. Where no escape Jira drops stops a smiley, carry the text in the `{adf}` macro instead.
Touches:
- `spec/wiki.md`: Inline
- `src/wiki/emit/text-escaping.ts`: `escapes`, `opensSmiley`
- `src/wiki/emit/adf-to-jira-wiki.test.ts` (small)
### 193. Write ADF as Jira wiki markup, carrying in Jira's `{adf}` macro each node and mark wiki markup cannot spell.
The lossless wiki writer, as `spec/wiki.md` spells each node. Ships with a fixture per node and
@@ -286,7 +300,7 @@ Topic 41858 asks for ADF as plain text. `adfToPlainText` now writes tables, imag
### 197. Write a heading holding a node wiki markup cannot spell as `h1.` to `h6.` with that node's inline carry, rather than carrying the whole heading.
Today `adfToLosslessJiraWiki` carries a heading as a block whenever one inline node in it rides, such as a `status`, since `spec/wiki.md` lets an inline carry stand on its own only inside a paragraph. A Jira user then sees no heading where the document has one. Extend the paragraph rule to headings in `spec/wiki.md` → The carry, and in `headingSpelling` in `src/wiki/emit/spelled-blocks.ts`; item 195's reader must read an inline carry inside a heading line.
Today `adfToLosslessJiraWiki` carries a heading as a block whenever any inline node in it rides, such as a `status`, since `spec/wiki.md` lets an inline carry stand on its own only inside a paragraph. A Jira user then sees no heading where the document has one. Extend the paragraph rule to headings in `spec/wiki.md` → The carry, and in `headingSpelling` in `src/wiki/emit/spelled-blocks.ts`; item 195's reader must then read an inline carry inside a heading line too.
### 82. Give the directive tests and fixtures random UUID v7 ids in place of `a-1`, `a`, `x` and `h`.