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

Answer prose round 1: 0 🔴, 12 🟡 (0 misread); reword the marker messages, comments and docs, and name the directive-form exceptions

This commit is contained in:
2026-11-19 17:43:29 +01:00
committed by Lillem4n
parent 57af3c17f2
commit 5945a62b54
12 changed files with 42 additions and 44 deletions
-1
View File
@@ -92,7 +92,6 @@ function withoutEmptyKeys<T extends AdfMark | AdfNode>(held: T): T {
return kept
}
// Jira gives every block an id, which the lossless writer carries in a marker beside the block's CommonMark spelling.
const localId = fc.oneof({ arbitrary: fc.stringMatching(/^[0-9a-f-]{1,12}$/), weight: 3 }, { arbitrary: textOf(0), weight: 1 })
function occasionallyIdentified(arbitrary: Arbitrary<AdfNode>): Arbitrary<AdfNode> {
+9 -9
View File
@@ -173,13 +173,13 @@ test('names a marker with no block below it to carry its id', () => {
assert.deepEqual(errorPath(losslessMarkdownToAdf('Part.\n\n> !adf:{localId=p}\n')), ['content', 1, 'content', 0])
})
test('names the blank line a marker and its block keep or leave out', () => {
test('refuses a marker whose blank line does not match its block', () => {
refused('!adf:{localId=p}\n\nPart.\n', 'malformed-directive', { line: 1, offset: 0 }, 'right above')
refused('!adf:{localId=r}\n---\n', 'malformed-directive', { line: 1, offset: 0 }, 'blank line')
refused('!adf:{localId=l}\n2. a\n', 'malformed-directive', { line: 1, offset: 0 }, 'blank line')
})
test('names the block a marker line stands above that carries its id another way, or not at all', () => {
test('refuses a marker line above a block that takes its id another way or has none', () => {
refused('!adf:{localId=h}\n# Part\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'heading', 'end of its line')
refused('> !adf:{localId=p}\n> Part.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'end of its last line')
refused('- !adf:{localId=p}\n Part.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'list item')
@@ -200,7 +200,7 @@ test('names a trailing marker standing where the id takes the line above, or on
refused('## Part\t!adf:{localId=h}\n', 'malformed-directive', { line: 1, offset: 0 }, 'completes no directive')
})
test('reads a trailing marker ahead of the link reference definitions and the setext underline its paragraph holds', () => {
test('reads a trailing marker before the link reference definitions and the setext underline of its paragraph', () => {
refused('> [a]: /u !adf:{localId=p}\n', 'malformed-directive', { line: 1, offset: 0 }, 'link reference definitions')
refused('[a]: /u !adf:{localId=h}\n===\n', 'malformed-directive', { line: 1, offset: 0 }, 'link reference definitions')
assert.deepEqual(read(losslessMarkdownToAdf('Part !adf:{localId=h}\n===\n')), [node('heading', { level: 1, localId: 'h' }, text('Part'))])
@@ -217,18 +217,18 @@ test('names an item marker standing before no paragraph', () => {
test('names a marker spelled outside its one canonical form', () => {
refused('!adf:{localId="p"}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId=p')
refused('!adf:{level=2}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'level')
refused('!adf:{}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'carries nothing')
refused('!adf:{}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'no key')
refused('- !adf:{localId=i style=x} Part\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'style')
refused('# Part !adf:{localId="h"}\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId=h')
refused('!adf:{localId=p b=1}\nPart.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alphabetical')
refused('!adf:{localId=p} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alone on its line')
refused('> !adf:{localId=p} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alone on its line')
for (const item of ['- !adf:{localId=i}Part\n', '- !adf:{localId=i} Part\n', '- !adf:{localId=i} \tPart\n']) refused(item, 'malformed-directive', { line: 1, offset: 0 }, 'alone on its line')
refused('!adf:{localId=p} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'a line of its own')
refused('> !adf:{localId=p} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'a line of its own')
for (const item of ['- !adf:{localId=i}Part\n', '- !adf:{localId=i} Part\n', '- !adf:{localId=i} \tPart\n']) refused(item, 'malformed-directive', { line: 1, offset: 0 }, 'a line of its own')
refused('- !adf:{localId=i Part\n', 'malformed-directive', { line: 1, offset: 0 }, 'key=value')
refused('!adf:{a=1 localId=p}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'carries a;')
refused('!adf:{a=1 localId=p}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'holds a;')
})
test('leaves a marker the text it is in the readers claiming no directive, and writes none there', () => {
test('reads an `!adf:{…}` as text where the reader claims no directive, and the portable writer drops the ids', () => {
assert.deepEqual(read(portableMarkdownToAdf('!adf:{localId=p}\nPart.\n')), [said(undefined, '!adf:{localId=p} Part.')])
assert.deepEqual(read(commonMarkToAdf('- !adf:{localId=i} Part !adf:{localId=p}\n')), [node('bulletList', {}, node('listItem', {}, said(undefined, '!adf:{localId=i} Part !adf:{localId=p}')))])
assert.equal(written(adfToPortableMarkdown(document(...jiraDescription))), [
+3 -4
View File
@@ -19,7 +19,7 @@ export function spellIdMarker(id: string): string {
return `${directivePrefix}${spellIdAttributes(id)}`
}
// A quoted id may hold the opener, so the marker is the last opener whose attributes end the text; one at the start would trail nothing.
// A quoted id may hold the opener, so the marker is the last opener whose attributes end the text; an opener at index 0 has no text before it, so it is no trailing marker.
export function readTrailingMarker(text: string): TrailingMarker | undefined {
for (let start = text.lastIndexOf(trailingOpener); start > 0; start = text.lastIndexOf(trailingOpener, start - 1)) {
const read = readAttributes(text, start + trailingOpener.length - 1, pairFault)
@@ -45,9 +45,8 @@ export function readItemMarker(text: string): { attributes: DirectiveAttributes;
export function readMarkerId(attributes: DirectiveAttributes, type: string, path: ConvertErrorPath): Result<string> {
const spelled = attributes.get(idKey)
if (spelled === undefined || attributes.size !== 1) {
let other = 'nothing'
for (const key of attributes.keys()) if (key !== idKey) other = key
return failure('unsupported-node-shape', `an ${markerOpener}…} marker carries ${idKey} alone: this one on a ${type} carries ${other}; write the ${type} as its directive to carry more`, path)
const others = [...attributes.keys()].filter((key) => key !== idKey)
return failure('unsupported-node-shape', `an ${markerOpener}…} marker holds ${idKey} alone: this one on a ${type} holds ${others.length === 0 ? 'no key' : others.join(', ')}; write the ${type} as its directive to carry more`, path)
}
const spelling = spellStringAttribute(spelled.decoded)
if (spelling !== spelled.spelling) return failure('unsupported-node-shape', `${type} spells its ${idKey} attribute as ${idKey}=${spelling}`, path)
+1 -1
View File
@@ -65,7 +65,7 @@ export const directiveEscape = `\\${directivePrefix} keeps the prefix literal`
const closerFault = `a closer carries nothing after its name: this one does; ${directiveEscape}`
const emptyFault = 'an empty {attrs} is omitted unless the { itself claims the directive: this one spells {}'
const openerFault = `a directive opener reads a name, one bare argument and {attrs}, one space apart: this one does not; ${directiveEscape}`
const markerFault = `an ${markerOpener}…} marker stands alone on its line, after a list item's marker or at the end of a paragraph's or heading's last line: this one does not; ${directiveEscape}`
const markerFault = `an ${markerOpener}…} marker stands on a line of its own, right after a list item's marker, or at the end of a paragraph's or heading's last line: this one does none of these; ${directiveEscape}`
const orderFault = 'the {attrs} keys read in alphabetical order'
export const pairFault = `${attributePairCause}; ${directiveEscape}`
const prefixFault = `an unescaped ${directivePrefix} completes no directive; ${directiveEscape}`
+2 -3
View File
@@ -258,10 +258,9 @@ export function quotedBlocks(node: AdfNode, path: ConvertErrorPath, depth: numbe
return success(commonMarkText(markedLines(id, quotedText(bodyText(joinBlocks(inner.value.blocks, 'quote'))), false), inner.value.headroom))
}
// The id a marker carries beside a CommonMark spelling holding the attributes `spelled` names; `undefined` where the node holds another attribute, or an id no marker carries.
type MarkedId = { id?: string }
// The portable reduction drops every id, so only the lossless writer meets one.
// The id a marker holds beside a CommonMark spelling of the attributes `spelled` names; `undefined` where the node holds another attribute, or an id no marker holds. The portable reduction drops every id, so only the lossless writer meets one.
function markedId(node: AdfNode, ...spelled: string[]): MarkedId | undefined {
if (!holdsOnlyAttributes(node, [...spelled, idKey])) return undefined
const id = nodeAttrs(node)[idKey]
@@ -358,7 +357,7 @@ function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, writing:
return emitDirectiveBlock(node, ordered ? blockNodes.orderedList : blockNodes.bulletList, path, depth, () => success({ blocks: directiveItems(walked), headroom: headroom - 1 }))
}
// The line after an item's marker holds its own id, so an item whose first block takes the line above for its id, or whose id stands beside no paragraph, has no CommonMark spelling.
// An item's id sits right after its list marker, before its first paragraph's text. An item has no CommonMark spelling when its first block would put its own marker on that line, or when it has an id and no first paragraph.
function holdsItemMarker(item: WalkedItem): boolean {
const [first] = item.walk.blocks
if (first?.node.type === 'paragraph' && first.spelling === 'commonmark') return true
+1 -1
View File
@@ -616,7 +616,7 @@ function takeParagraph(walk: Walk): Extract<Block, { kind: 'fault' }> | Paragrap
return { kind: 'paragraph', position: kept?.position ?? leaf.position, ...trailedText(text, trailed) }
}
// No trailing key where no marker trails, so a block reads as it did before markers.
// A block holding no marker has no `trailing` key.
function trailedText(text: string, trailed: TrailingMarker | undefined): { text: string; trailing?: Read<DirectiveAttributes> } {
return trailed === undefined ? { text } : { text, trailing: trailed.attributes }
}
+4 -4
View File
@@ -116,7 +116,7 @@ function markedNode(node: AdfNode, block: Exclude<Block, MarkerBlock>, line: Mar
if (trailing.fault !== undefined) return positioned(faulted(trailing.fault, path), block.position)
if (line !== undefined) return positioned(failure('malformed-directive', twoMarkers, path), block.position)
if (block.kind === 'paragraph' && !trails) {
return positioned(failure('unsupported-node-shape', `a paragraph carries its ${markerOpener}…} marker on the line above it, unless it opens a quote or a list item: move this one there`, path), block.position)
return positioned(failure('unsupported-node-shape', `a paragraph carries its ${markerOpener}…} marker on the line above it, unless it opens a quote or a list item: move this one to the line above the paragraph`, path), block.position)
}
if (node.type !== block.kind) return positioned(failure('unsupported-node-shape', `this paragraph reads as a ${node.type}, whose id rides its directive: write the ${node.type} as its directive`, path), block.position)
return identified(node, trailing.value, path, block.position)
@@ -130,12 +130,12 @@ function lineMarkedNode(node: AdfNode, block: Exclude<Block, MarkerBlock>, line:
const gap = block.position.line - line.position.line
if (gap !== (blankBelowMarker(block) ? 2 : 1)) {
const placement = blankBelowMarker(block) ? `one blank line parts an ${markerOpener}…} marker from the ${node.type} below it, which CommonMark would otherwise read with the marker` : `an ${markerOpener}…} marker stands on the line right above its ${node.type}`
return positioned(failure('malformed-directive', `${placement}: this one stands ${gap} lines above it`, path), line.position)
return positioned(failure('malformed-directive', `${placement}: this one stands ${gap === 1 ? '1 line' : `${gap} lines`} above it`, path), line.position)
}
return identified(node, line.attributes, path, line.position)
}
// A text line above a rule makes a setext heading, and one above a list its marker cannot interrupt continues the line.
// A text line above a rule makes a setext heading, and above a list whose marker cannot interrupt a paragraph it continues that paragraph.
function blankBelowMarker(block: Exclude<Block, MarkerBlock>): boolean {
if (block.kind === 'rule') return true
if (block.kind !== 'bulletList' && block.kind !== 'orderedList') return false
@@ -297,7 +297,7 @@ function listItemNode(blocks: readonly Block[], reading: Reading, path: ConvertE
const [first] = blocks
if (first?.kind !== 'marker') return containerNode({ type: 'listItem' }, blocks, reading, path, depth, 'trailing')
if (first.placement === 'line') {
return positioned(failure('unsupported-node-shape', `a list item's first line carries the item's own ${markerOpener}…} marker, right after its list marker: write the list as directives to give the block opening this item an id`, path), first.position)
return positioned(failure('unsupported-node-shape', `a list item's first line carries the item's own ${markerOpener}…} marker, right after its list marker: write the list as directives, or end a paragraph opening this item with a marker, to give the block opening this item an id`, path), first.position)
}
const item = containerNode({ type: 'listItem' }, blocks.slice(1), reading, path, depth, 'trailing')
if (!item.ok) return item