3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 22:25: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
- 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
+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
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.
+18 -10
View File
@@ -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`
+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 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' }],
+1 -1
View File
@@ -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
}
+4 -3
View File
@@ -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<AdfMacro> | 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)
+1 -1
View File
@@ -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')
})
+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 }
const address = /https?:\/\/[^\s)'"<>!|[\]{}\\]*/y
const anchorMacro = /\{anchor(?::[^}\n]*)?\}/y
const anchorMacro = /\{anchor(?::[^{}\n]*)?\}/y
const characterMarks: ReadonlyMap<string, AdfMark> = new Map([
['*', { type: 'strong' }],
['+', { type: 'underline' }],
@@ -34,7 +34,7 @@ const characterMarks: ReadonlyMap<string, AdfMark> = 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)
+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: '{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 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 } })
})
+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 }
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<AdfDocument, ParseError> {
function readWiki(wiki: string): Result<AdfDocument> {
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<string, string> {
const read = new Map<string, string>()
for (const parameter of held.split(separator)) {
+20 -1
View File
@@ -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.