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:
@@ -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
@@ -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
@@ -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`
|
||||||
|
|||||||
@@ -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' }],
|
||||||
|
|||||||
@@ -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
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -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)
|
||||||
|
|||||||
@@ -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')
|
||||||
})
|
})
|
||||||
|
|||||||
@@ -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)
|
||||||
|
|||||||
@@ -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 } })
|
||||||
|
})
|
||||||
|
|||||||
@@ -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)) {
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|||||||
Reference in New Issue
Block a user