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

Describe each CommonMark spelling beside the emitter's spelling it names

This commit is contained in:
2026-11-14 11:06:31 +01:00
committed by Lillem4n
parent b088d4f075
commit 5d41b4be26
5 changed files with 58 additions and 41 deletions
+17
View File
@@ -1031,3 +1031,20 @@ Read most (opens and searches):
- `src/result.ts` 2 - `src/result.ts` 2
- `MIGRATION.md` 1 - `MIGRATION.md` 1
- `src/adf/plain-copy.ts` 1 - `src/adf/plain-copy.ts` 1
## Reading cost, chunk d1552a8c1f4c, finished 2026-11-14T09:55:35Z
222598 new input tokens before the first commit.
Read most (opens and searches):
- `src/markdown/parse/markdown-to-adf.test.ts` 69
- `src/adf/document.test.ts` 25
- `src/html/parse/html-to-adf.test.ts` 11
- `todo.md` 7
- `docs/decisions.md` 5
- `src/result.ts` 3
- `ci.sh` 2
- `README.md` 1
- `docker-runner.sh` 1
- `package.json` 1
+38 -9
View File
@@ -155,18 +155,47 @@ export function spellingMemo(): SpellingMemo {
return { ask, take } return { ask, take }
} }
type ReadableSpelling = {
// The lossless flavour's spelling in words, for the refusal of a directive that CommonMark spells.
describe: (node: AdfNode) => string
spell: (node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing) => Result<EmittedBlock> | undefined
}
const readableSpellings: ReadonlyMap<string, ReadableSpelling> = new Map<string, ReadableSpelling>([
['blockquote', {
describe: () => 'each line behind `> `',
spell: (node, path, depth, writing) => holdsOnlyAttributes(node, []) ? quotedBlocks(node, path, depth, writing, (body) => alertEscaped(body, writing)) : undefined,
}],
['bulletList', { describe: () => 'each item behind `- `, or behind `* ` where the list right before it takes `- `', spell: tryList }],
['codeBlock', {
describe: () => 'its text in a fence of more backticks than any run it holds, its language after the opening fence',
spell: (node, _path, _depth, writing) => readableText(tryCodeBlock(node, writing.flavour)),
}],
['heading', { describe: () => 'one `#` per level before its text, `## Title` at level 2', spell: (node, path, _depth, writing) => tryHeading(node, path, writing.flavour) }],
['mediaSingle', {
describe: () => '`![alt](url)`, or `[![alt](url)](href)` when linked',
spell: (node, _path, _depth, writing) => readableText(tryImage(node, writing.flavour)),
}],
['orderedList', {
describe: (node) => {
const order = String(nodeAttrs(node)['order'])
return `each item behind its number, counting up from \`${order}. \`, or from \`${order}) \` where the list right before it takes \`.\``
},
spell: tryList,
}],
['paragraph', { describe: () => 'its text alone', spell: (node, path, _depth, writing) => tryParagraph(node, path, writing.flavour) }],
['rule', { describe: () => '`---`', spell: (node) => readableText(tryRule(node)) }],
['table', { describe: () => 'a pipe table', spell: (node, path, _depth, writing) => readableText(tryPipeTable(node, path, writing.flavour)) }],
])
export function describeCommonMarkSpelling(node: AdfNode): string | undefined {
return readableSpellings.get(node.type)?.describe(node)
}
function spellReadableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> | undefined { function spellReadableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> | undefined {
const own = writing.flavour === 'portable' ? writing.blocks.spell(node, path, depth, writing) : undefined const own = writing.flavour === 'portable' ? writing.blocks.spell(node, path, depth, writing) : undefined
if (own !== undefined) return own if (own !== undefined) return own
if (node.type === 'blockquote') return holdsOnlyAttributes(node, []) ? quotedBlocks(node, path, depth, writing, (body) => alertEscaped(body, writing)) : undefined return readableSpellings.get(node.type)?.spell(node, path, depth, writing)
if (node.type === 'bulletList' || node.type === 'orderedList') return tryList(node, path, depth, writing)
if (node.type === 'codeBlock') return readableText(tryCodeBlock(node, writing.flavour))
if (node.type === 'heading') return tryHeading(node, path, writing.flavour)
if (node.type === 'mediaSingle') return readableText(tryImage(node, writing.flavour))
if (node.type === 'paragraph') return tryParagraph(node, path, writing.flavour)
if (node.type === 'rule') return readableText(tryRule(node))
if (node.type === 'table') return readableText(tryPipeTable(node, path, writing.flavour))
return undefined
} }
function readableText(text: string | undefined): Result<EmittedBlock> | undefined { function readableText(text: string | undefined): Result<EmittedBlock> | undefined {
+1 -1
View File
@@ -1,3 +1,3 @@
// The only file `parse/` imports from `emit/` (docs/decisions.md §The source parts by ADF and format). // The only file `parse/` imports from `emit/` (docs/decisions.md §The source parts by ADF and format).
export { commonMarkSpelling, spellingMemo, type SpellingMemo } from './adf-to-markdown.ts' export { commonMarkSpelling, describeCommonMarkSpelling, spellingMemo, type SpellingMemo } from './adf-to-markdown.ts'
export { openingLinkTakesDirective } from './inline-line.ts' export { openingLinkTakesDirective } from './inline-line.ts'
+2 -20
View File
@@ -5,7 +5,7 @@ import type { ConvertFault } from '../../result.ts'
import type { LineContainer } from '../line-container.ts' import type { LineContainer } from '../line-container.ts'
import type { LinkDefinitions } from '../inline-content.ts' import type { LinkDefinitions } from '../inline-content.ts'
import { carryFenceType, readCarriedBlock } from '../opaque-carry.ts' import { carryFenceType, readCarriedBlock } from '../opaque-carry.ts'
import { commonMarkSpelling, spellingMemo, type SpellingMemo } from '../emit/spelling-questions.ts' import { commonMarkSpelling, describeCommonMarkSpelling, spellingMemo, type SpellingMemo } from '../emit/spelling-questions.ts'
import { documentAttribute, documentName, documentSpelling } from '../directive/block.ts' import { documentAttribute, documentName, documentSpelling } from '../directive/block.ts'
import { emptyKeys, nodeAttrs } from '../../adf/document.ts' import { emptyKeys, nodeAttrs } from '../../adf/document.ts'
import { failure, faulted, positioned, success, type ConvertErrorPath, type ParseError, type Result } from '../../result.ts' import { failure, faulted, positioned, success, type ConvertErrorPath, type ParseError, type Result } from '../../result.ts'
@@ -132,28 +132,10 @@ function directiveNode(block: DirectiveBlock, reading: Reading, path: ConvertErr
const readable = withinEngineLimits(() => commonMarkSpelling(built.value, path, depth, { flavour: 'lossless', memo: reading.memo })) const readable = withinEngineLimits(() => commonMarkSpelling(built.value, path, depth, { flavour: 'lossless', memo: reading.memo }))
if (!readable.ok) return readable if (!readable.ok) return readable
if (!readable.value) return built if (!readable.value) return built
const spelling = spellingToWrite(built.value) const spelling = describeCommonMarkSpelling(built.value)
return failure('unsupported-node-shape', `${built.value.type} takes the CommonMark spelling, not the directive form${spelling === undefined ? '' : `: write ${spelling}`}`, path) return failure('unsupported-node-shape', `${built.value.type} takes the CommonMark spelling, not the directive form${spelling === undefined ? '' : `: write ${spelling}`}`, path)
} }
function spellingToWrite(node: AdfNode): string | undefined {
if (node.type !== 'orderedList') return commonMarkSpellings.get(node.type)
const order = String(nodeAttrs(node)['order'])
return `each item behind its number, counting up from \`${order}. \`, or from \`${order}) \` where the list right before it takes \`.\``
}
// One entry per node `commonMarkSpelling` spells in the lossless flavour, kept here because this refusal is its only reader; a node missing here is refused naming no spelling.
const commonMarkSpellings: ReadonlyMap<string, string> = new Map([
['blockquote', 'each line behind `> `'],
['bulletList', 'each item behind `- `, or behind `* ` where the list right before it takes `- `'],
['codeBlock', 'its text in a fence of more backticks than any run it holds, its language after the opening fence'],
['heading', 'one `#` per level before its text, `## Title` at level 2'],
['mediaSingle', '`![alt](url)`, or `[![alt](url)](href)` when linked'],
['paragraph', 'its text alone'],
['rule', '`---`'],
['table', 'a pipe table'],
])
function directiveBody(read: BlockDirectiveNode, blocks: Block[] | undefined, reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode> { function directiveBody(read: BlockDirectiveNode, blocks: Block[] | undefined, reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode> {
const { contentModel, node } = read const { contentModel, node } = read
if (blocks === undefined) return success(node) if (blocks === undefined) return success(node)
-11
View File
@@ -12,7 +12,6 @@
| 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 |
|---|---|---|---|---|---|---|---|---|---|---|---| |---|---|---|---|---|---|---|---|---|---|---|---|
| 173 | 0.4.0 | | principle | **Move each CommonMark spelling's description out of `commonMarkSpellings`, beside the emitter's spelling it describes.** | 2 | 1 | 1 | 2 | 4 | code health by 1 | 4.4 |
| 147 | 0.4.0 | | | **Ship `adfToPlainText`, writing a document's content with no markup, under a README goal for plain text.** | 2 | 2 | 1 | 3 | 4 | 3 by 4 | 4.2 | | 147 | 0.4.0 | | | **Ship `adfToPlainText`, writing a document's content with no markup, under a README goal for plain text.** | 2 | 2 | 1 | 3 | 4 | 3 by 4 | 4.2 |
| 141 | 0.4.0 | | decision | **Write `strike` as HTML in `adfToHtml` and read it back in `htmlToAdf`, in place of the carry element.** | 1 | 1 | 1 | 1 | 2 | 6 by 2 | 4.0 | | 141 | 0.4.0 | | decision | **Write `strike` as HTML in `adfToHtml` and read it back in `htmlToAdf`, in place of the carry element.** | 1 | 1 | 1 | 1 | 2 | 6 by 2 | 4.0 |
| 135 | 0.4.0 | | | **Write media, media groups and captions as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 2.0 | | 135 | 0.4.0 | | | **Write media, media groups and captions as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 2.0 |
@@ -50,16 +49,6 @@
## Details ## Details
### 173. Move each CommonMark spelling's description out of `commonMarkSpellings`, beside the emitter's spelling it describes.
`commonMarkSpellings` (`src/markdown/parse/markdown-to-adf.ts`) restates in prose the spellings
`spellReadableBlock` (`src/markdown/emit/adf-to-markdown.ts`) owns, such as "each item behind `- `,
or behind `* ` where …". A changed spelling leaves the refusal naming the old one, and a node
missing from the map is refused naming no spelling. Put each description beside the spelling and
export it through `emit/spelling-questions.ts`, the one import `parse/` may take from `emit/`, and
drop the comment at `markdown-to-adf.ts:145` that keeps them apart.
Technical principle: DRY. Found by the principles audit of the release review of 0.3.0, 2026-11-08.
### 147. Ship `adfToPlainText`, writing a document's content with no markup, under a README goal for plain text. ### 147. Ship `adfToPlainText`, writing a document's content with no markup, under a README goal for plain text.
Asked on the Atlassian developer community for search indexing, notifications, emails and CSV Asked on the Atlassian developer community for search indexing, notifications, emails and CSV