From de091a1c4ed019070cb3acce4df58c3ddbb913dd Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 17 Nov 2026 02:12:22 +0100 Subject: [PATCH] =?UTF-8?q?Answer=20prose=20round=201:=200=20=F0=9F=94=B4,?= =?UTF-8?q?=2013=20=F0=9F=9F=A1=20(0=20misread);=20define=20markup=20chara?= =?UTF-8?q?cters=20once,=20state=20when=20empty=20values=20and=20carriage?= =?UTF-8?q?=20returns=20ride,=20and=20fix=20the=20comments=20and=20test=20?= =?UTF-8?q?names?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- spec/wiki.md | 37 +++++++------ src/adf/carried-json.ts | 2 +- src/wiki/carry.ts | 3 +- src/wiki/emit/adf-to-jira-wiki.test.ts | 75 ++++++++++++-------------- src/wiki/emit/adf-to-jira-wiki.ts | 3 +- src/wiki/emit/inline-line.ts | 3 +- src/wiki/emit/spelled-blocks.ts | 4 +- todo.md | 20 +++++-- 8 files changed, 79 insertions(+), 68 deletions(-) diff --git a/spec/wiki.md b/spec/wiki.md index ce7e910..86d7d04 100644 --- a/spec/wiki.md +++ b/spec/wiki.md @@ -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:}`, a line feed, the text, a line feed, `{code}`; for `""`, `{noformat}`, the text, `{noformat}` the same way | the same, reading a `{code:}` 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 | `!!`, or `!\|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 | `!!`, or `!\|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=}`, 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:]` | 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:]` | 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` | `[\|]`, with `\|` 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 diff --git a/src/adf/carried-json.ts b/src/adf/carried-json.ts index 1b0cf7e..9ad0085 100644 --- a/src/adf/carried-json.ts +++ b/src/adf/carried-json.ts @@ -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) diff --git a/src/wiki/carry.ts b/src/wiki/carry.ts index 384175f..2e162b9 100644 --- a/src/wiki/carry.ts +++ b/src/wiki/carry.ts @@ -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) diff --git a/src/wiki/emit/adf-to-jira-wiki.test.ts b/src/wiki/emit/adf-to-jira-wiki.test.ts index 167b0de..06ca428 100644 --- a/src/wiki/emit/adf-to-jira-wiki.test.ts +++ b/src/wiki/emit/adf-to-jira-wiki.test.ts @@ -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}`, () => { diff --git a/src/wiki/emit/adf-to-jira-wiki.ts b/src/wiki/emit/adf-to-jira-wiki.ts index 7b1f8d5..c7fcc63 100644 --- a/src/wiki/emit/adf-to-jira-wiki.ts +++ b/src/wiki/emit/adf-to-jira-wiki.ts @@ -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()) { diff --git a/src/wiki/emit/inline-line.ts b/src/wiki/emit/inline-line.ts index 7317fd2..bee4e87 100644 --- a/src/wiki/emit/inline-line.ts +++ b/src/wiki/emit/inline-line.ts @@ -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) diff --git a/src/wiki/emit/spelled-blocks.ts b/src/wiki/emit/spelled-blocks.ts index 9ad9c80..418a68f 100644 --- a/src/wiki/emit/spelled-blocks.ts +++ b/src/wiki/emit/spelled-blocks.ts @@ -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() diff --git a/todo.md b/todo.md index 31c37a1..20f17cc 100644 --- a/todo.md +++ b/todo.md @@ -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`.