From 5d41b4be26ba40550e9ef94b8c2abbf022d97423 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sat, 14 Nov 2026 11:06:31 +0100 Subject: [PATCH] Describe each CommonMark spelling beside the emitter's spelling it names --- docs/reading-cost.md | 17 +++++++++ src/markdown/emit/adf-to-markdown.ts | 47 ++++++++++++++++++++----- src/markdown/emit/spelling-questions.ts | 2 +- src/markdown/parse/markdown-to-adf.ts | 22 ++---------- todo.md | 11 ------ 5 files changed, 58 insertions(+), 41 deletions(-) diff --git a/docs/reading-cost.md b/docs/reading-cost.md index 0355dd4..341e117 100644 --- a/docs/reading-cost.md +++ b/docs/reading-cost.md @@ -1031,3 +1031,20 @@ Read most (opens and searches): - `src/result.ts` 2 - `MIGRATION.md` 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 diff --git a/src/markdown/emit/adf-to-markdown.ts b/src/markdown/emit/adf-to-markdown.ts index e243bcd..0572baf 100644 --- a/src/markdown/emit/adf-to-markdown.ts +++ b/src/markdown/emit/adf-to-markdown.ts @@ -155,18 +155,47 @@ export function spellingMemo(): SpellingMemo { 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 | undefined +} + +const readableSpellings: ReadonlyMap = new Map([ + ['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 | undefined { const own = writing.flavour === 'portable' ? writing.blocks.spell(node, path, depth, writing) : undefined if (own !== undefined) return own - if (node.type === 'blockquote') return holdsOnlyAttributes(node, []) ? quotedBlocks(node, path, depth, writing, (body) => alertEscaped(body, writing)) : undefined - 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 + return readableSpellings.get(node.type)?.spell(node, path, depth, writing) } function readableText(text: string | undefined): Result | undefined { diff --git a/src/markdown/emit/spelling-questions.ts b/src/markdown/emit/spelling-questions.ts index d876a84..511bb7c 100644 --- a/src/markdown/emit/spelling-questions.ts +++ b/src/markdown/emit/spelling-questions.ts @@ -1,3 +1,3 @@ // 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' diff --git a/src/markdown/parse/markdown-to-adf.ts b/src/markdown/parse/markdown-to-adf.ts index 96aba31..02151ea 100644 --- a/src/markdown/parse/markdown-to-adf.ts +++ b/src/markdown/parse/markdown-to-adf.ts @@ -5,7 +5,7 @@ import type { ConvertFault } from '../../result.ts' import type { LineContainer } from '../line-container.ts' import type { LinkDefinitions } from '../inline-content.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 { emptyKeys, nodeAttrs } from '../../adf/document.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 })) if (!readable.ok) return readable 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) } -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 = 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 { const { contentModel, node } = read if (blocks === undefined) return success(node) diff --git a/todo.md b/todo.md index 655bc96..8cbfd10 100644 --- a/todo.md +++ b/todo.md @@ -12,7 +12,6 @@ | 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 | | 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 | @@ -50,16 +49,6 @@ ## 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. Asked on the Atlassian developer community for search indexing, notifications, emails and CSV