3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-19 14:45:44 +01:00

Answer stability round 1: 1 🔴, 3 🟡 (0 misread); stop each macro parameter at the next brace, read a code text's CRLF lines as line feeds and carry a code text holding a carriage return, and read the document carry whatever whitespace surrounds it

This commit is contained in:
2026-11-17 06:51:24 +01:00
committed by Lillem4n
parent 6f9e4ec3a8
commit 89639b84ef
11 changed files with 88 additions and 47 deletions
+1 -1
View File
@@ -99,7 +99,7 @@ In `docs/decisions.md`:
- Jira wiki markup spellings the help leaves open are a writer panel's picks - 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 - 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 - `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 ## 1. Nothing about any consumer in the library
+20 -17
View File
@@ -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 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. 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 2026-11-17, the implementer of `jiraWikiToAdf`. Goals 1, 6 and 11. Plan item 201 asks the
below that differ from Jira's. Goals 1, 6 and 11. maintainer to confirm the readings below that differ from Jira's.
Valid while `spec/wiki.md` §What only the reader reads lists them. 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. 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: with the path `[]`, since no node exists yet:
- An `{adf}` macro left open, or holding anything but one ADF node's JSON, is - 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. `unsupported-node-shape`: its text is no node. A carry fence holding bad JSON is refused the
An inline macro closes on its line, since a line feed ends its paragraph. same way in markdown. So is a macro inside a line that closes on a later line: the writers
- List markers past 500, or carried JSON nested past it, are `unsupported-nesting-depth` write such a macro on one line.
(§Nothing recurses unbounded). - 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. - A block macro after anything else on a line is text. Jira reads one inside a line.
Jira also reads them inside a line. - An image is a block, so one that shares its line is text. Jira shows it inline.
- An image reads only alone on its line, as its `mediaSingle` is a block. Inside a line it is text.
- A delimiter reads by the rule the writer escapes by (`spec/wiki.md` §Marks), so every string the - 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 The reader follows Jira in two places a reader could take either way. A block macro left open
`://`, since Jira reads any other as an attachment's name, so the writer carries an image whose holds the rest of the markup. An image address holds `://`, since Jira reads any other as an
`url` has none. attachment's name, so the writer carries an image whose `url` has none.
+18 -10
View File
@@ -1,6 +1,6 @@
# Jira wiki markup # 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 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 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`. "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, 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, 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 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 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. 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 `-`. - At a line's start, `#`, `*` and `-`.
Jira keeps a backslash before `:`, `;`, `.`, `,`, a letter, a digit or another backslash as text. 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; - a backslash, a line feed or a carriage return;
- `http://` or `https://`, which Jira would link; - `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; - 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: The writers never write these, and the reader reads them as follows:
- `{anchor:name}` reads as nothing, since no ADF node holds a bookmark. - `{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 - An address standing bare, `http://` or `https://` first, reads as its text linked to it, less a
name. So does an image that shares its line with anything else. `.`, `,`, `;` or `?` ending it.
- `{code}`, `{noformat}`, `{panel}` and `{quote}` open and close a block only at a line's start, - `!name.ext!`, whose address holds no `://`, reads as text: no ADF node holds an attachment by
and read as text inside a line. One left open holds the rest of the markup. 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 - 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. `unsupported-node-shape`. So is one inside a line that closes on a later line.
- `---` and `--` read as `—` and `–`. - 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 - 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 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` before its `(` or its closing `)` stops it: `\(y)` and `:\)` read as text. The `emoji`'s `text`
+1
View File
@@ -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 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 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 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 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 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' }], ['a code block whose language is no string', { attrs: { language: 5 }, content: [text('x')], type: 'codeBlock' }],
+1 -1
View File
@@ -118,7 +118,7 @@ function codeText(node: AdfNode): string | undefined {
const [text, ...others] = nodeContent(node) const [text, ...others] = nodeContent(node)
const code = text?.text const code = text?.text
if (!holdsOnlyAttributes(node, ['language']) || typeof language !== 'string' || text === undefined || code === undefined || others.length > 0 || !isUnmarkedSpellableText(text)) return undefined 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}` if (language === '') return `{noformat}\n${code}\n{noformat}`
return codeLanguages.includes(language) ? `{code:${language}}\n${code}\n{code}` : undefined return codeLanguages.includes(language) ? `{code:${language}}\n${code}\n{code}` : undefined
} }
+4 -3
View File
@@ -8,16 +8,17 @@ export type AdfMacro = { end: number; inline: boolean; node: AdfNode }
const closer = '{adf}' const closer = '{adf}'
const holder = 'an {adf} macro' 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<AdfMacro> | undefined { export function readAdfMacro(wiki: string, at: number, end: number): Read<AdfMacro> | undefined {
opener.lastIndex = at opener.lastIndex = at
const opened = opener.exec(wiki) const opened = opener.exec(wiki)
if (opened === null) return undefined if (opened === null) return undefined
const start = opener.lastIndex const start = opener.lastIndex
const close = wiki.indexOf(closer, start) 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")) 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 if (value.fault !== undefined) return value
const bounded = carriedNesting(value.value, largestNesting) const bounded = carriedNesting(value.value, largestNesting)
+1 -1
View File
@@ -4,6 +4,6 @@ import test from 'node:test'
import { colourNames } from './colour-names.ts' 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') assert.equal(createHash('sha256').update(JSON.stringify(colourNames)).digest('hex'), 'b0342a8a5a0071cd9f90a78f9490277db0c3632a976b2a9745d08aa8e51eb1fa')
}) })
+5 -5
View File
@@ -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 } 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 address = /https?:\/\/[^\s)'"<>!|[\]{}\\]*/y
const anchorMacro = /\{anchor(?::[^}\n]*)?\}/y const anchorMacro = /\{anchor(?::[^{}\n]*)?\}/y
const characterMarks: ReadonlyMap<string, AdfMark> = new Map([ const characterMarks: ReadonlyMap<string, AdfMark> = new Map([
['*', { type: 'strong' }], ['*', { type: 'strong' }],
['+', { type: 'underline' }], ['+', { type: 'underline' }],
@@ -34,7 +34,7 @@ const characterMarks: ReadonlyMap<string, AdfMark> = new Map([
['_', { type: 'em' }], ['_', { type: 'em' }],
['~', { attrs: { type: 'sub' }, type: 'subsup' }], ['~', { attrs: { type: 'sub' }, type: 'subsup' }],
]) ])
const colourMacro = /\{color(?::([^}\n]*))?\}/y const colourMacro = /\{color(?::([^{}\n]*))?\}/y
const keepsBackslash = /[\p{L}\p{N}\s:;.,]/u const keepsBackslash = /[\p{L}\p{N}\s:;.,]/u
const plain = /[^\n\\*_\-+^~{}?[|:;(h]+/y const plain = /[^\n\\*_\-+^~{}?[|:;(h]+/y
const space = /\s/u const space = /\s/u
@@ -150,7 +150,7 @@ function closeLink(scan: Scan, link: Link): number {
return link.end 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 { function dash(scan: Scan, at: number): number {
const { end, wiki } = scan const { end, wiki } = scan
let after = at + 1 let after = at + 1
@@ -179,7 +179,7 @@ function smiley(scan: Scan, at: number): number {
for (const spelled of smileys) { for (const spelled of smileys) {
const emoji = smileyEmoji[spelled] const emoji = smileyEmoji[spelled]
const next = pointAt(scan, at + spelled.length) 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 { id, shortName } = emoji
const text = /^[0-9a-f]+$/.test(id) ? String.fromCodePoint(Number.parseInt(id, 16)) : shortName const text = /^[0-9a-f]+$/.test(id) ? String.fromCodePoint(Number.parseInt(id, 16)) : shortName
push(scan, { node: { attrs: { id, shortName, text }, type: 'emoji' } }) push(scan, { node: { attrs: { id, shortName, text }, type: 'emoji' } })
@@ -228,7 +228,7 @@ function bracket(scan: Scan, at: number): number {
if (character === '\\') close += 1 if (character === '\\') close += 1
else if (character === '|') bars.push(close) 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 const [first, second] = bars
if (first === undefined) return bracketed(scan, at, wiki.slice(at + 1, close)) if (first === undefined) return bracketed(scan, at, wiki.slice(at + 1, close))
const href = wiki.slice(first + 1, second ?? close) const href = wiki.slice(first + 1, second ?? close)
+8 -2
View File
@@ -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: '{noformat} as a codeBlock of language ""', reads: [code('', 'a\n\n b')], wiki: '{noformat}\na\n\n b\n{noformat}' },
{ name: '{code:<language>} 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: '{code:<language>} 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} 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} 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: '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!' }, { 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[] = [ 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: '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: '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]|' }, { 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 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 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 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 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 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}' }, { 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', () => { test('names the line of a refusal after empty lines', () => {
assert.equal(read('\n\n{adf}'), 'unsupported-node-shape at line 3, offset 2') 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 } })
})
+9 -6
View File
@@ -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 } type Reading = { containers: Container[]; levels: Level[]; paragraph: AdfNode[] | undefined; rows: AdfNode[] | undefined; wiki: string }
const codeMacro = /\{(code|noformat)(?::([^}\n]*))?\}/y const codeMacro = /\{(code|noformat)(?::([^}\n]*))?\}/y
const codeEdge = /\r?\n|/y
const documentCarry = '{adf:display=block}\n{"type":"doc","version":1}\n{adf}' const documentCarry = '{adf:display=block}\n{"type":"doc","version":1}\n{adf}'
const image = /^!([^\s!|]+)(?:\|([^!]*))?!$/ const image = /^!([^\s!|]+)(?:\|([^!]*))?!$/
const itemMarker = /^([*#]+|-) +/ const itemMarker = /^([*#]+|-) +/
@@ -38,7 +39,7 @@ export function jiraWikiToAdf(wiki: string): Result<AdfDocument, ParseError> {
function readWiki(wiki: string): Result<AdfDocument> { function readWiki(wiki: string): Result<AdfDocument> {
if (typeof wiki !== 'string') return notAString(wiki, 'Jira wiki markup') 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 root: Container = { content: [], kind: 'document' }
const reading: Reading = { containers: [root], levels: [], paragraph: undefined, rows: undefined, wiki } const reading: Reading = { containers: [root], levels: [], paragraph: undefined, rows: undefined, wiki }
let at = 0 let at = 0
@@ -78,7 +79,7 @@ function readLine(reading: Reading, line: Line): Fault | number {
return readTextLine(reading, line) 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 { function readMacro(reading: Reading, start: number): Fault | number | undefined {
const { containers, wiki } = reading const { containers, wiki } = reading
if (!wiki.startsWith('{', start)) return undefined if (!wiki.startsWith('{', start)) return undefined
@@ -103,14 +104,16 @@ function readMacro(reading: Reading, start: number): Fault | number | undefined
return panelMacro.lastIndex 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 { function readCode(reading: Reading, from: number, name: string, held: string | undefined): number {
const { wiki } = reading const { wiki } = reading
const closer = `{${name}}` const closer = `{${name}}`
const close = wiki.indexOf(closer, from) const close = wiki.indexOf(closer, from)
const end = close === -1 ? wiki.length : close const end = close === -1 ? wiki.length : close
const start = from + (wiki.startsWith('\n', from) ? 1 : 0) codeEdge.lastIndex = from
const text = wiki.slice(start, Math.max(start, end - (wiki.startsWith('\n', end - 1) ? 1 : 0))) 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 [first = ''] = (held ?? '').split('|')
const language = name === 'noformat' ? '' : first === '' || first.includes('=') ? 'java' : first.trim().toLowerCase() 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) 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 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<string, string> { function parameters(held: string, separator: string): Map<string, string> {
const read = new Map<string, string>() const read = new Map<string, string>()
for (const parameter of held.split(separator)) { for (const parameter of held.split(separator)) {
+20 -1
View File
@@ -6,12 +6,13 @@
`Bar = 0.1` `Bar = 0.1`
`Next ID = 201` `Next ID = 202`
## Items ## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score | | 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 | | 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 | | 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 | | 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 ## 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. ### 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. 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.