mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-18 06:05:43 +01:00
Describe each CommonMark spelling beside the emitter's spelling it names
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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<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: () => '``, or `[](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 {
|
||||
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<EmittedBlock> | undefined {
|
||||
|
||||
@@ -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'
|
||||
|
||||
@@ -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<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', '``, or `[](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> {
|
||||
const { contentModel, node } = read
|
||||
if (blocks === undefined) return success(node)
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user