diff --git a/AGENTS.md b/AGENTS.md index c246c91..cba1509 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,7 +99,7 @@ In `docs/decisions.md`: - Jira wiki markup spellings the help leaves open are a writer panel's picks - A plain wiki spelling stands for the attributes Jira's editor writes, and any other attribute rides the carry - `htmlToAdf` reads any HTML, with no option and no second call -- The wiki reader refuses only a broken `{adf}` macro and markup past the engine's limits, and reads every other string +- The wiki reader refuses only a broken `{adf}` macro, nesting past 500 levels and output past the engine's limits, and reads every other string ## 1. Nothing about any consumer in the library diff --git a/docs/decisions.md b/docs/decisions.md index 6fa10d2..b6a9e7f 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1550,30 +1550,33 @@ A panel of three developers, one each for the bot, the viewer/editor app and the picked this over `htmlToAdf(html, { foreign: true })` and `anyHtmlToAdf(html)`. None of them knows up front whether HTML is foreign, so a flag or a second name makes them guess. -## The wiki reader refuses only a broken `{adf}` macro and markup past the engine's limits, and reads every other string +## The wiki reader refuses only a broken `{adf}` macro, nesting past 500 levels and output past the engine's limits, and reads every other string -2026-11-17, the implementer of `jiraWikiToAdf`; the maintainer has not yet confirmed the readings -below that differ from Jira's. Goals 1, 6 and 11. -Valid while `spec/wiki.md` §What only the reader reads lists them. +2026-11-17, the implementer of `jiraWikiToAdf`. Goals 1, 6 and 11. Plan item 201 asks the +maintainer to confirm the readings below that differ from Jira's. +Valid while `jiraWikiToAdf` returns a `Result`. Wiki markup has no syntax error: Jira shows markup it can't read as text, and so does the reader. -Two inputs can't read as text without losing content, and are refused at the line they start on, +Three inputs can't read as text without losing content. Each is refused at the line it starts on, with the path `[]`, since no node exists yet: - An `{adf}` macro left open, or holding anything but one ADF node's JSON, is - `unsupported-node-shape`: the text is no node, as a carry fence holding bad JSON is in markdown. - An inline macro closes on its line, since a line feed ends its paragraph. -- List markers past 500, or carried JSON nested past it, are `unsupported-nesting-depth` - (§Nothing recurses unbounded). + `unsupported-node-shape`: its text is no node. A carry fence holding bad JSON is refused the + same way in markdown. So is a macro inside a line that closes on a later line: the writers + write such a macro on one line. +- A list line of more than 500 markers, or carried JSON nested past 500 levels, is + `unsupported-nesting-depth` (§Nothing recurses unbounded). +- Markup that reads past the engine's limits is `engine-limit`. -The reader is simpler than Jira in three places, each a string the writers never write: +The reader differs from Jira in four places, each a string the writers never write. `spec/wiki.md` +§What only the reader reads states each reading: -- `{code}`, `{noformat}`, `{panel}` and `{quote}` open and close a block only at a line's start. - Jira also reads them inside a line. -- An image reads only alone on its line, as its `mediaSingle` is a block. Inside a line it is text. +- A block macro after anything else on a line is text. Jira reads one inside a line. +- An image is a block, so one that shares its line is text. Jira shows it inline. - A delimiter reads by the rule the writer escapes by (`spec/wiki.md` §Marks), so every string the - writer writes reads back, where Jira's own rule differs at an edge such as `x^2^`. + writer writes reads back. Jira's own rule differs at an edge such as `x^2^`. +- `-- ` at a line's start is an en dash. Jira reads a nested bullet. -A block macro left open holds the rest of the markup, as Jira renders it. An image address holds -`://`, since Jira reads any other as an attachment's name, so the writer carries an image whose -`url` has none. +The reader follows Jira in two places a reader could take either way. A block macro left open +holds the rest of the markup. An image address holds `://`, since Jira reads any other as an +attachment's name, so the writer carries an image whose `url` has none. diff --git a/spec/wiki.md b/spec/wiki.md index 0bef7d8..4a3e08e 100644 --- a/spec/wiki.md +++ b/spec/wiki.md @@ -1,6 +1,6 @@ # Jira wiki markup -What `adfToLosslessJiraWiki`, `adfToLossyJiraWiki` and the Jira wiki markup reader do with each ADF +What `adfToLosslessJiraWiki`, `adfToLossyJiraWiki` and the reader, `jiraWikiToAdf`, do with each ADF node and mark. Each table's middle column is what both writers write, and the last is what the reader reads; "The lossy writer" says where the lossy writer differs. The source is Atlassian's "Text Formatting Notation Help", which Jira serves at `/secure/WikiRendererHelpAction.jspa?section=all`. @@ -55,7 +55,7 @@ string. The names the help lists for a `codeBlock`: actionscript, ada, applescript, bash, c, c#, c++, css, erlang, go, groovy, haskell, html, java, javascript, json, lua, nyan, objc, perl, php, python, r, ruby, scala, sql, swift, visualbasic, xml and yaml. A `codeBlock` with any other `language`, none -included, or a text that is empty or holds `{code}` or `{noformat}`, rides the carry. +included, or a text that is empty or holds a carriage return, `{code}` or `{noformat}`, rides the carry. A value other than the one a table names, an absent attribute included, rides the carry: so does a `width`, a merged cell and a colour. @@ -83,9 +83,8 @@ as whitespace, and a node's edge inside the line as punctuation: - At a line's start, `#`, `*` and `-`. Jira keeps a backslash before `:`, `;`, `.`, `,`, a letter, a digit or another backslash as text. -So a backslash protects none of these, and a text holding one rides the carry: +So a backslash protects none of these, and a text holding one, or no character at all, rides the carry: -- no character at all; - a backslash, a line feed or a carriage return; - `http://` or `https://`, which Jira would link; - the `h` of `h1.` to `h6.` or the `b` of `bq.` at a line's start, in any case; @@ -135,13 +134,22 @@ says `adfToPlainText` does, in wiki markup: The writers never write these, and the reader reads them as follows: - `{anchor:name}` reads as nothing, since no ADF node holds a bookmark. -- `!name.ext!`, an address holding no `://`, reads as its text: no ADF node holds an attachment by - name. So does an image that shares its line with anything else. -- `{code}`, `{noformat}`, `{panel}` and `{quote}` open and close a block only at a line's start, - and read as text inside a line. One left open holds the rest of the markup. +- An address standing bare, `http://` or `https://` first, reads as its text linked to it, less a + `.`, `,`, `;` or `?` ending it. +- `!name.ext!`, whose address holds no `://`, reads as text: no ADF node holds an attachment by + name. So does an image that shares its line with anything else, its address read as a bare one. +- `{code}`, `{noformat}`, `{panel}` and `{quote}` open a block at a line's start or right after + another of them, and read as text after anything else on a line. `{panel}` and `{quote}` close + one in the same places, `{code}` and `{noformat}` wherever the closing macro stands. One left + open holds the rest of the markup. - An `{adf}` macro left open, or holding anything but one ADF node's JSON, is refused as - `unsupported-node-shape`. An inline one closes on its line. -- `---` and `--` read as `—` and `–`. + `unsupported-node-shape`. So is one inside a line that closes on a later line. +- In a `{code}` or `{noformat}` text, a carriage return before a line feed reads as nothing, so + markup whose lines end in both reads as markup whose lines end in a line feed. +- `---` and `--` with whitespace or the line's edge on each side read as `—` and `–`. So `-- ` at + a line's start is no nested bullet. +- `h1.` to `h6.` and `bq.` read with a space after the dot or none, and in lower case alone, as + Jira reads them. - A smiley reads as the `emoji` Jira reads it as, wherever the next character is not a letter or a digit and whatever comes before it: `x:)` and `f(x)` read, `a:Pb` and `:)x` don't, and a backslash before its `(` or its closing `)` stops it: `\(y)` and `:\)` read as text. The `emoji`'s `text` diff --git a/src/wiki/emit/adf-to-jira-wiki.test.ts b/src/wiki/emit/adf-to-jira-wiki.test.ts index d7bbcd0..93d6789 100644 --- a/src/wiki/emit/adf-to-jira-wiki.test.ts +++ b/src/wiki/emit/adf-to-jira-wiki.test.ts @@ -365,6 +365,7 @@ const riddenBlocks: [string, AdfNode][] = [ ['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 an empty text', { attrs: { language: 'java' }, content: [text('')], type: 'codeBlock' }], + ['a code block whose text holds a carriage return', { attrs: { language: 'java' }, content: [text('a\r\nb')], 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 whose language is no string', { attrs: { language: 5 }, content: [text('x')], type: 'codeBlock' }], diff --git a/src/wiki/emit/spelled-blocks.ts b/src/wiki/emit/spelled-blocks.ts index e68f549..b4323a2 100644 --- a/src/wiki/emit/spelled-blocks.ts +++ b/src/wiki/emit/spelled-blocks.ts @@ -118,7 +118,7 @@ function codeText(node: AdfNode): string | undefined { const [text, ...others] = nodeContent(node) const code = text?.text if (!holdsOnlyAttributes(node, ['language']) || typeof language !== 'string' || text === undefined || code === undefined || others.length > 0 || !isUnmarkedSpellableText(text)) return undefined - if (code === '' || code.includes('{code}') || code.includes('{noformat}')) return undefined + if (code === '' || code.includes('\r') || code.includes('{code}') || code.includes('{noformat}')) return undefined if (language === '') return `{noformat}\n${code}\n{noformat}` return codeLanguages.includes(language) ? `{code:${language}}\n${code}\n{code}` : undefined } diff --git a/src/wiki/parse/adf-macro.ts b/src/wiki/parse/adf-macro.ts index 2057564..7645d63 100644 --- a/src/wiki/parse/adf-macro.ts +++ b/src/wiki/parse/adf-macro.ts @@ -8,16 +8,17 @@ export type AdfMacro = { end: number; inline: boolean; node: AdfNode } const closer = '{adf}' const holder = 'an {adf} macro' -const opener = /\{adf(?::([^}\n]*))?\}/y +const opener = /\{adf(?::([^{}\n]*))?\}/y -// spec/wiki.md, The carry: `undefined` where no `{adf}` macro opens at `at`. The macro closes before `end`. +// spec/wiki.md, The carry: `undefined` where no `{adf}` macro opens at `at`. A macro closing past `end` is refused. export function readAdfMacro(wiki: string, at: number, end: number): Read | undefined { opener.lastIndex = at const opened = opener.exec(wiki) if (opened === null) return undefined const start = opener.lastIndex const close = wiki.indexOf(closer, start) - if (close === -1 || close + closer.length > end) return { fault: refusal('closes with {adf}: this one is left open') } + if (close === -1) return { fault: refusal('closes with {adf}: this one is left open') } + if (close + closer.length > end) return { fault: refusal('inside a line closes on that line: this one closes on a later line') } const value = carriedValue(wiki.slice(start, close), holder, refusal("holds one ADF node's JSON: this is no JSON")) if (value.fault !== undefined) return value const bounded = carriedNesting(value.value, largestNesting) diff --git a/src/wiki/parse/colour-names.test.ts b/src/wiki/parse/colour-names.test.ts index d421499..52156c6 100644 --- a/src/wiki/parse/colour-names.test.ts +++ b/src/wiki/parse/colour-names.test.ts @@ -4,6 +4,6 @@ import test from 'node:test' import { colourNames } from './colour-names.ts' -test("holds CSS Color Module Level 4's 148 named colours, by the digest of the published list", () => { +test("holds the table as it was when checked against CSS Color Module Level 4's 148 named colours, by the table's digest", () => { assert.equal(createHash('sha256').update(JSON.stringify(colourNames)).digest('hex'), 'b0342a8a5a0071cd9f90a78f9490277db0c3632a976b2a9745d08aa8e51eb1fa') }) diff --git a/src/wiki/parse/inline.ts b/src/wiki/parse/inline.ts index 77f9ff5..fe3478d 100644 --- a/src/wiki/parse/inline.ts +++ b/src/wiki/parse/inline.ts @@ -26,7 +26,7 @@ type TextPiece = { marks: AdfMark[]; text: string } type Scan = { end: number; inCell: boolean; link: Link | undefined; opened: Opened[]; pieces: Piece[]; run: TextPiece | undefined; start: number; wiki: string } const address = /https?:\/\/[^\s)'"<>!|[\]{}\\]*/y -const anchorMacro = /\{anchor(?::[^}\n]*)?\}/y +const anchorMacro = /\{anchor(?::[^{}\n]*)?\}/y const characterMarks: ReadonlyMap = new Map([ ['*', { type: 'strong' }], ['+', { type: 'underline' }], @@ -34,7 +34,7 @@ const characterMarks: ReadonlyMap = new Map([ ['_', { type: 'em' }], ['~', { attrs: { type: 'sub' }, type: 'subsup' }], ]) -const colourMacro = /\{color(?::([^}\n]*))?\}/y +const colourMacro = /\{color(?::([^{}\n]*))?\}/y const keepsBackslash = /[\p{L}\p{N}\s:;.,]/u const plain = /[^\n\\*_\-+^~{}?[|:;(h]+/y const space = /\s/u @@ -150,7 +150,7 @@ function closeLink(scan: Scan, link: Link): number { return link.end } -// spec/wiki.md, What only the reader reads: `--` and `---` between whitespace or the line's edges are dashes, and no run of hyphens strikes. +// spec/wiki.md, What only the reader reads: no longer run of hyphens is a dash, and none strikes. function dash(scan: Scan, at: number): number { const { end, wiki } = scan let after = at + 1 @@ -179,7 +179,7 @@ function smiley(scan: Scan, at: number): number { for (const spelled of smileys) { const emoji = smileyEmoji[spelled] const next = pointAt(scan, at + spelled.length) - if (emoji === undefined || !scan.wiki.startsWith(spelled, at) || at + spelled.length > scan.end || (next !== undefined && word.test(next))) continue + if (emoji === undefined || !scan.wiki.startsWith(spelled, at) || (next !== undefined && word.test(next))) continue const { id, shortName } = emoji const text = /^[0-9a-f]+$/.test(id) ? String.fromCodePoint(Number.parseInt(id, 16)) : shortName push(scan, { node: { attrs: { id, shortName, text }, type: 'emoji' } }) @@ -228,7 +228,7 @@ function bracket(scan: Scan, at: number): number { if (character === '\\') close += 1 else if (character === '|') bars.push(close) } - if (close >= end || bars.length > 2) return plainCharacter(scan, at) + if (close >= end) return plainCharacter(scan, at) const [first, second] = bars if (first === undefined) return bracketed(scan, at, wiki.slice(at + 1, close)) const href = wiki.slice(first + 1, second ?? close) diff --git a/src/wiki/parse/jira-wiki-to-adf.test.ts b/src/wiki/parse/jira-wiki-to-adf.test.ts index e01ec8d..82b0771 100644 --- a/src/wiki/parse/jira-wiki-to-adf.test.ts +++ b/src/wiki/parse/jira-wiki-to-adf.test.ts @@ -117,7 +117,8 @@ const blocks: Case[] = [ { name: '{noformat} as a codeBlock of language ""', reads: [code('', 'a\n\n b')], wiki: '{noformat}\na\n\n b\n{noformat}' }, { name: '{code:} in lowercase, {code} as java', reads: [code('python', 'x'), code('java', 'y')], wiki: '{code:Python}\nx\n{code}\n\n{code}\ny\n{code}' }, { name: 'a {code} dropping its title and borderStyle', reads: [code('sql', 'x'), code('java', 'y')], wiki: '{code:sql|title=T|borderStyle=solid}\nx\n{code}\n\n{code:title=T}\ny\n{code}' }, - { name: 'a code text whole, markup, carriage returns and edge blanks included', reads: [code('', ' *a* \r\n{quote}\n')], wiki: '{noformat}\n *a* \r\n{quote}\n\n{noformat}' }, + { name: 'a code text whole, markup and edge blanks included', reads: [code('', ' *a* \n{quote}\n')], wiki: '{noformat}\n *a* \n{quote}\n\n{noformat}' }, + { name: 'a code text of lines ending in a carriage return and a line feed with a line feed between them', reads: [code('', 'a\n\nb\rc')], wiki: '{noformat}\r\na\r\n\r\nb\rc\r\n{noformat}' }, { name: 'a {code} holding nothing as a codeBlock holding no content', reads: [code('java')], wiki: '{code}\n{code}' }, { name: 'a {code} left open as closing at the end', reads: [code('java', 'a')], wiki: '{code}\na' }, { name: 'an image alone on its line as a mediaSingle', reads: [image('http://a.b/c.png')], wiki: '!http://a.b/c.png!' }, @@ -267,6 +268,8 @@ for (const { name, wiki } of roundTrips) { } const edgeCases: Case[] = [ + { name: 'a heading and a quote with no space after the dot', reads: [node('heading', { level: 2 }, text('x')), node('blockquote', undefined, paragraph(text('y')))], wiki: 'h2.x\nbq.y' }, + { name: 'an anchor macro whose name holds an opening brace as text', reads: [paragraph(text('{anchor:a'))], wiki: '{anchor:a{anchor:b}' }, { name: 'a table on each side of a list', reads: [node('table', { isNumberColumnEnabled: false, layout: 'default' }, node('tableRow', undefined, node('tableCell', undefined, paragraph(text('a'))))), node('bulletList', undefined, node('listItem', undefined, paragraph(text('b')))), node('table', { isNumberColumnEnabled: false, layout: 'default' }, node('tableRow', undefined, node('tableCell', undefined, paragraph(text('c')))))], wiki: '|a|\n* b\n|c|' }, { name: 'text after the macro closing a quote as a paragraph after the quote', reads: [node('blockquote', undefined, paragraph(text('a'))), paragraph(text('b'))], wiki: '{quote}\na\n{quote}b' }, { name: 'a backslash before a bar in a cell\'s link text', reads: [node('table', { isNumberColumnEnabled: false, layout: 'default' }, node('tableRow', undefined, node('tableCell', undefined, paragraph(text('a|b', { attrs: { href: 'http://c.d' }, type: 'link' })))))], wiki: '|[a\\|b|http://c.d]|' }, @@ -288,7 +291,6 @@ const edgeCases: Case[] = [ { name: 'a line after an item holding only an anchor', reads: [{ content: [{ content: [{ type: 'paragraph' }], type: 'listItem' }], type: 'bulletList' }, { content: [{ text: 'b', type: 'text' }], type: 'paragraph' }], wiki: '* {anchor:a}\nb' }, { name: 'a link holding a bar in a cell', reads: [{ attrs: { isNumberColumnEnabled: false, layout: 'default' }, content: [{ content: [{ content: [{ content: [{ marks: [{ attrs: { href: 'http://b.c' }, type: 'link' }], text: 'a', type: 'text' }], type: 'paragraph' }], type: 'tableCell' }], type: 'tableRow' }], type: 'table' }], wiki: '|[a|http://b.c]|' }, { name: 'a link holding an empty title', reads: [{ content: [{ text: '[a|', type: 'text' }, { marks: [{ attrs: { href: 'http://b.c' }, type: 'link' }], text: 'http://b.c', type: 'text' }, { text: '|]', type: 'text' }], type: 'paragraph' }], wiki: '[a|http://b.c|]' }, - { name: 'a list after a paragraph', reads: [{ content: [{ text: 'a', type: 'text' }], type: 'paragraph' }, { content: [{ content: [{ content: [{ text: 'b', type: 'text' }], type: 'paragraph' }], type: 'listItem' }], type: 'bulletList' }], wiki: 'a\n* b' }, { name: 'a numbered list after a bullet list', reads: [{ content: [{ content: [{ content: [{ text: 'a', type: 'text' }], type: 'paragraph' }], type: 'listItem' }], type: 'bulletList' }, { attrs: { order: 1 }, content: [{ content: [{ content: [{ text: 'b', type: 'text' }], type: 'paragraph' }], type: 'listItem' }], type: 'orderedList' }], wiki: '* a\n# b' }, { name: 'a paragraph after a closed quote', reads: [{ content: [{ content: [{ text: 'a', type: 'text' }], type: 'paragraph' }], type: 'blockquote' }, { content: [{ text: 'b', type: 'text' }], type: 'paragraph' }], wiki: '{quote}\na\n{quote}\nb' }, { name: 'a quote left open and empty', reads: [{ content: [{ type: 'paragraph' }], type: 'blockquote' }], wiki: '{quote}' }, @@ -338,3 +340,7 @@ test('refuses an inline {adf} macro that closes at the next line\'s start', () = test('names the line of a refusal after empty lines', () => { assert.equal(read('\n\n{adf}'), 'unsupported-node-shape at line 3, offset 2') }) + +test('reads the carry of a document holding no content key, whatever whitespace surrounds it', () => { + for (const around of ['\n', '\r\n', ' ']) assert.deepEqual(jiraWikiToAdf(`${around}{adf:display=block}\n{"type":"doc","version":1}\n{adf}${around}`), { ok: true, value: { type: 'doc', version: 1 } }) +}) diff --git a/src/wiki/parse/jira-wiki-to-adf.ts b/src/wiki/parse/jira-wiki-to-adf.ts index feeafab..526a316 100644 --- a/src/wiki/parse/jira-wiki-to-adf.ts +++ b/src/wiki/parse/jira-wiki-to-adf.ts @@ -23,6 +23,7 @@ type Line = { end: number; next: number; start: number; text: string } type Reading = { containers: Container[]; levels: Level[]; paragraph: AdfNode[] | undefined; rows: AdfNode[] | undefined; wiki: string } const codeMacro = /\{(code|noformat)(?::([^}\n]*))?\}/y +const codeEdge = /\r?\n|/y const documentCarry = '{adf:display=block}\n{"type":"doc","version":1}\n{adf}' const image = /^!([^\s!|]+)(?:\|([^!]*))?!$/ const itemMarker = /^([*#]+|-) +/ @@ -38,7 +39,7 @@ export function jiraWikiToAdf(wiki: string): Result { function readWiki(wiki: string): Result { if (typeof wiki !== 'string') return notAString(wiki, 'Jira wiki markup') - if (wiki === documentCarry) return success({ type: 'doc', version: 1 }) + if (wiki.trim() === documentCarry) return success({ type: 'doc', version: 1 }) const root: Container = { content: [], kind: 'document' } const reading: Reading = { containers: [root], levels: [], paragraph: undefined, rows: undefined, wiki } let at = 0 @@ -78,7 +79,7 @@ function readLine(reading: Reading, line: Line): Fault | number { return readTextLine(reading, line) } -// A macro opens and closes a block only at its line's start, and reads as text anywhere else; `undefined` where none stands there. +// `undefined` where no block macro stands at `start`: a line's start, or the end of the macro before it. function readMacro(reading: Reading, start: number): Fault | number | undefined { const { containers, wiki } = reading if (!wiki.startsWith('{', start)) return undefined @@ -103,14 +104,16 @@ function readMacro(reading: Reading, start: number): Fault | number | undefined return panelMacro.lastIndex } -// The text stands between the macros whole, less the line feed after the opening one and the line feed before the closing one. +// The text stands between the macros whole, less the line ending after the opening one and the line ending before the closing one. function readCode(reading: Reading, from: number, name: string, held: string | undefined): number { const { wiki } = reading const closer = `{${name}}` const close = wiki.indexOf(closer, from) const end = close === -1 ? wiki.length : close - const start = from + (wiki.startsWith('\n', from) ? 1 : 0) - const text = wiki.slice(start, Math.max(start, end - (wiki.startsWith('\n', end - 1) ? 1 : 0))) + codeEdge.lastIndex = from + const start = from + (codeEdge.exec(wiki)?.[0].length ?? 0) + const ending = wiki.startsWith('\r\n', end - 2) ? 2 : wiki.startsWith('\n', end - 1) ? 1 : 0 + const text = wiki.slice(start, Math.max(start, end - ending)).replaceAll('\r\n', '\n') const [first = ''] = (held ?? '').split('|') const language = name === 'noformat' ? '' : first === '' || first.includes('=') ? 'java' : first.trim().toLowerCase() return pushBlock(reading, { attrs: { language }, ...(text === '' ? {} : { content: [{ text, type: 'text' }] }), type: 'codeBlock' }, close === -1 ? wiki.length : close + closer.length) @@ -250,7 +253,7 @@ function blocksOf({ containers }: Reading): AdfNode[] | undefined { return containers.at(-1)?.content } -// `key=value` parameters, a parameter holding no `=` under the key it is. +// `key=value` parameters; one holding no `=` is its own key and value. function parameters(held: string, separator: string): Map { const read = new Map() for (const parameter of held.split(separator)) { diff --git a/todo.md b/todo.md index 3da4b3b..cffcee4 100644 --- a/todo.md +++ b/todo.md @@ -6,12 +6,13 @@ `Bar = 0.1` -`Next ID = 201` +`Next ID = 202` ## Items | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score | |---|---|---|---|---|---|---|---|---|---|---|---| +| 201 | 0.4.0 | | question | **Confirm or change the readings `jiraWikiToAdf` takes that differ from Jira's.** | 2 | 2 | 2 | 4 | 2 | 11 by 3, 6 by 2 | 5.7 | | 200 | 0.4.0 | | | **Carry a link whose `href` Jira shows as text, and read `[x]` and `[a\|x]` with such an address as text.** | 2 | 2 | 2 | 4 | 3 | 11 by 4, 6 by 2 | 5.1 | | 194 | 0.4.0 | | 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 | | 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 | @@ -48,6 +49,24 @@ ## Details +### 201. Confirm or change the readings `jiraWikiToAdf` takes that differ from Jira's. + +Item 195 made these choices without the maintainer, and `docs/decisions.md` §The wiki reader refuses only a broken `{adf}` macro, nesting past 500 levels and output past the engine's limits, and reads every other string records them. Each is a string the writers never write. Confirm each, or say what it reads to instead: + +- A broken `{adf}` macro is refused as `unsupported-node-shape`, with the path `[]`, where it could read as text. +- `{code}`, `{noformat}`, `{panel}` and `{quote}` after anything else on a line read as text, where Jira reads them inside a line. +- An image that shares its line reads as text, where Jira shows it inline. +- An `{adf}` macro inside a line that closes on a later line is refused. +- A delimiter reads by the rule the writer escapes by, where Jira's own rule differs at an edge such as `x^2^`. +- `-- ` at a line's start reads as an en dash and text, where Jira reads a nested bullet. +- A list line of up to 500 markers reads, and the writers refuse the document past 250 levels of list as `unsupported-nesting-depth`. + +Touches: +- `src/wiki/parse/jira-wiki-to-adf.ts`: `readMacro`, `readItem`, `readLine` +- `src/wiki/parse/inline.ts`: `delimiter`, `dash` +- `spec/wiki.md`: `## What only the reader reads` +- `docs/decisions.md`: the entry named above + ### 200. Carry a link whose `href` Jira shows as text, and read `[x]` and `[a|x]` with such an address as text. Item 195's probes of Jira found that it shows `[x]` and `[a|x]` as text where `x` is no address it links, such as a bare word. The lossless writer writes a `link` with such an `href` as `[a|x]`, so the link is lost when Jira renders the markup, and `jiraWikiToAdf` reads both as a `link`, unlike Jira. Probe which addresses Jira links (a scheme, `#anchor`, `mailto:`, a path), record the list in `spec/wiki.md`, carry every other `href`, and read the same strings as text.