13b - link takes the directive form where CommonMark cannot spell it, unspellable-link leaves the code list

src/adf-schema.test.ts

@@ -18,7 +18,7 @@ type Spelled = [string, Map<string, AttributeKind>]
 
 const carried = ['alignment', 'annotation', 'backgroundColor', 'blockCard', 'bodiedRule', 'breakout', 'dataConsumer', 'embedCard', 'fontSize', 'fragment', 'indentation', 'inlineExtension', 'placeholder']
 const definitionReference = '#/definitions/'
-const gaps = ['link.collection', 'link.id', 'link.occurrenceKey']
+const gaps: string[] = []
 const grammarOwn = ['doc', 'text']
 const readKeywords = ['$ref', 'additionalProperties', 'allOf', 'anyOf', 'enum', 'items', 'maxItems', 'maximum', 'minItems', 'minLength', 'minimum', 'pattern', 'properties', 'required', 'type']
 const root = join(dirname(fileURLToPath(import.meta.url)), '..', 'spec', 'adf-schema')

src/adf/mark-attributes.ts

@@ -4,7 +4,7 @@ export const markAttributes = {
   border: { color: 'string', size: 'number' },
   code: {},
   em: {},
-  link: { href: 'string', title: 'string' },
+  link: { collection: 'string', href: 'string', id: 'string', occurrenceKey: 'string', title: 'string' },
   strike: {},
   strong: {},
   subsup: { type: 'string' },

src/markdown/emit/adf-to-markdown.test.ts

@@ -82,15 +82,25 @@ test('spells a code block language no info string holds as an attribute', () =>
   assert.equal(language('a\tb'), '!adf:codeBlock {language="a\\tb"}\n```\n```\n!adf:/codeBlock\n')
 })
 
-test('refuses a link destination CommonMark cannot spell', () => {
-  const link = (href: string): AdfDocument => document(paragraph({ marks: [{ attrs: { href }, type: 'link' }], text: 't', type: 'text' }))
-  assert.equal(code(adfToMarkdown(link('https://example.com/a b>c'))), 'unspellable-link')
-  assert.equal(code(adfToMarkdown(link('<https://example.com/'))), 'unspellable-link')
-  assert.equal(code(adfToMarkdown(link('https://example.com/a\\b'))), 'unspellable-link')
-  assert.equal(code(adfToMarkdown(link('https://example.com/?a=1&amp;b=2'))), 'unspellable-link')
-  assert.equal(code(adfToMarkdown(link('https://example.com/a\nb'))), 'unspellable-link')
+test('spells a link destination CommonMark cannot as the directive link', () => {
+  const link = (href: string): string => markdown(adfToMarkdown(document(paragraph({ marks: [{ attrs: { href }, type: 'link' }], text: 't', type: 'text' }))))
+  assert.equal(link('https://example.com/a b>c'), '!adf:link[t]{href="https://example.com/a b>c"}\n')
+  assert.equal(link('<https://example.com/'), '!adf:link[t]{href="\\u003chttps://example.com/"}\n')
+  assert.equal(link('https://example.com/a\\b'), '!adf:link[t]{href="https://example.com/a\\\\b"}\n')
+  assert.equal(link('https://example.com/?a=1&amp;b=2'), '!adf:link[t]{href="https://example.com/?a=1\\u0026amp;b=2"}\n')
+  assert.equal(link('https://example.com/a\nb'), '!adf:link[t]{href="https://example.com/a\\nb"}\n')
   const entity = 'https://example.com/?a=1&amp;b=2'
-  assert.equal(code(adfToMarkdown(document(paragraph({ marks: [{ attrs: { href: entity }, type: 'link' }], text: entity, type: 'text' })))), 'unspellable-link')
+  const autolinkShaped = document(paragraph({ marks: [{ attrs: { href: entity }, type: 'link' }], text: entity, type: 'text' }))
+  assert.equal(markdown(adfToMarkdown(autolinkShaped)), '!adf:link[https://example.com/?a=1\\&amp;b=2]{href="https://example.com/?a=1\\u0026amp;b=2"}\n')
+})
+
+test('spells a link carrying an attribute CommonMark cannot as the directive link, and refuses none', () => {
+  const link = (attrs: Record<string, string>): string =>
+    markdown(adfToMarkdown(document(paragraph({ marks: [{ attrs, type: 'link' }], text: 't', type: 'text' }))))
+  assert.equal(link({ collection: 'c', href: 'https://example.com/' }), '!adf:link[t]{collection=c href="https://example.com/"}\n')
+  assert.equal(link({ href: 'https://example.com/', id: 'i' }), '!adf:link[t]{href="https://example.com/" id=i}\n')
+  assert.equal(link({ href: 'https://example.com/', occurrenceKey: 'k' }), '!adf:link[t]{href="https://example.com/" occurrenceKey=k}\n')
+  assert.equal(link({ href: 'https://example.com/', id: 'i', title: 'a\nb' }), '!adf:link[t]{href="https://example.com/" id=i title="a\\nb"}\n')
 })
 
 test('escapes the parenthesis a link destination leaves unbalanced, and no other', () => {
@@ -102,19 +112,20 @@ test('escapes the parenthesis a link destination leaves unbalanced, and no other
   assert.equal(link('https://example.com/a (b'), '[t](<https://example.com/a (b>)\n')
 })
 
-test('escapes the quote a link title holds, and refuses the rest', () => {
-  const titled = (title: string): AdfDocument =>
-    document(paragraph({ marks: [{ attrs: { href: 'https://example.com/', title }, type: 'link' }], text: 't', type: 'text' }))
-  assert.equal(markdown(adfToMarkdown(titled('He said "hi"'))), '[t](https://example.com/ "He said \\"hi\\"")\n')
-  assert.equal(code(adfToMarkdown(titled('a\nb'))), 'unspellable-link')
-  assert.equal(code(adfToMarkdown(titled('a\\b'))), 'unspellable-link')
+test('escapes the quote a link title holds, and spells the rest as the directive link', () => {
+  const titled = (title: string): string =>
+    markdown(adfToMarkdown(document(paragraph({ marks: [{ attrs: { href: 'https://example.com/', title }, type: 'link' }], text: 't', type: 'text' }))))
+  assert.equal(titled('He said "hi"'), '[t](https://example.com/ "He said \\"hi\\"")\n')
+  assert.equal(titled('a\nb'), '!adf:link[t]{href="https://example.com/" title="a\\nb"}\n')
+  assert.equal(titled('a\\b'), '!adf:link[t]{href="https://example.com/" title="a\\\\b"}\n')
+  assert.equal(titled('a &amp; b'), '!adf:link[t]{href="https://example.com/" title="a \\u0026amp; b"}\n')
 })
 
 test('carries a link mark the link spelling cannot write', () => {
   const carried = (mark: AdfMark): string => markdown(adfToMarkdown(document(paragraph({ marks: [mark], text: 't', type: 'text' }))))
   assert.equal(
-    carried({ attrs: { href: 'x', id: 'y' }, type: 'link' }),
-    '!adf:carry{json="{\\"marks\\":[{\\"attrs\\":{\\"href\\":\\"x\\",\\"id\\":\\"y\\"},\\"type\\":\\"link\\"}],\\"text\\":\\"t\\",\\"type\\":\\"text\\"}"}\n',
+    carried({ attrs: { href: 'x', rel: 'y' }, type: 'link' }),
+    '!adf:carry{json="{\\"marks\\":[{\\"attrs\\":{\\"href\\":\\"x\\",\\"rel\\":\\"y\\"},\\"type\\":\\"link\\"}],\\"text\\":\\"t\\",\\"type\\":\\"text\\"}"}\n',
   )
   assert.equal(carried({ attrs: { href: 4 }, type: 'link' }), '!adf:carry{json="{\\"marks\\":[{\\"attrs\\":{\\"href\\":4},\\"type\\":\\"link\\"}],\\"text\\":\\"t\\",\\"type\\":\\"text\\"}"}\n')
   assert.equal(carried({ type: 'link' }), '!adf:carry{json="{\\"marks\\":[{\\"type\\":\\"link\\"}],\\"text\\":\\"t\\",\\"type\\":\\"text\\"}"}\n')

src/markdown/emit/inline-line.ts

@@ -2,21 +2,20 @@ import type { AdfMark, AdfNode } from '../../adf/document.ts'
 import type { InlineDirective } from '../../adf/inline-directives.ts'
 import { assembleInlineLine, isSyntax, type InlineEscaping, type InlineSegment, type LineContainer, type NodeRange } from './line-escaping.ts'
 import { carriedInline } from '../opaque-carry.ts'
-import { claimsLine, holdsNullCharacter, isAutolink } from '../commonmark-grammar.ts'
-import { escapeUnbalanced, spellDestination, spellLinkTarget } from '../link-syntax.ts'
+import { claimsLine, holdsNullCharacter } from '../commonmark-grammar.ts'
+import { commonMarkLink, markSpelling, spellMarkAttributes, type CommonMarkLink } from '../mark-spellings.ts'
+import { escapeUnbalanced, spellDestination } from '../link-syntax.ts'
 import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts'
-import { holdsDirectivePrefix, slotLineEndingFault, spellInlineDirectiveOpener, spellInlineLeafDirective } from '../directive-syntax.ts'
-import { holdsEntityReference } from '../entity-references.ts'
 import { inlineDirective } from '../../adf/inline-directives.ts'
 import { largestNesting } from '../../nesting.ts'
 import { longestBacktickRun } from '../backtick-runs.ts'
-import { markSpelling, spellMarkAttributes } from '../mark-spellings.ts'
 import { nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts'
 import { sameMark } from '../../adf/editor-normal.ts'
+import { slotLineEndingFault, spellInlineDirectiveOpener, spellInlineLeafDirective } from '../directive-syntax.ts'
 import { spellInlineNodeAttributes } from './inline-directive-spelling.ts'
 import { spellTextDirective } from '../text-directive.ts'
 
-type EmittedLine = { line: string; segments: InlineSegment[] }
+type EmittedLine = { line: string; openingLinkAsDirective: boolean; segments: InlineSegment[] }
 
 type Emission = { carry: NodeRange; segments?: undefined } | { carry?: undefined; segments: InlineSegment[] }
 
@@ -24,13 +23,17 @@ type InlineContext = {
   atBlockEnd: boolean
   bracketed: boolean
   carried: ReadonlySet<number>
+  openingLinkAsDirective: boolean
   path: ConvertErrorPath
   spansLines: boolean
 }
 
 type InlineRun = { index: number; kind: 'marked'; mark: AdfMark; nodes: AdfNode[] } | { index: number; kind: 'plain'; node: AdfNode }
 
-type LineAttempt = { carry: NodeRange; line?: undefined } | { carry?: undefined; line: string }
+type LineAttempt =
+  | { carry: NodeRange; line?: undefined; openingLinkAsDirective?: undefined }
+  | { carry?: undefined; line?: undefined; openingLinkAsDirective: true }
+  | { carry?: undefined; line: string; openingLinkAsDirective?: undefined }
 
 export function emitInlineLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath): Result<string> {
   const emitted = emitLine(nodes, container, path)
@@ -38,6 +41,13 @@ export function emitInlineLine(nodes: readonly AdfNode[], container: LineContain
   return success(emitted.value.line)
 }
 
+// The parser asks which form a paragraph's opening link takes rather than restating the line rule (AGENTS.md §11).
+export function openingLinkTakesDirective(nodes: readonly AdfNode[], path: ConvertErrorPath): Result<boolean> {
+  const emitted = emitLine(nodes, 'paragraph', path)
+  if (!emitted.ok) return emitted
+  return success(emitted.value.openingLinkAsDirective)
+}
+
 export function tryPipeCell(nodes: readonly AdfNode[], path: ConvertErrorPath): string | undefined {
   const emitted = emitLine(nodes, 'table-cell', path)
   if (!emitted.ok) return undefined
@@ -47,18 +57,19 @@ export function tryPipeCell(nodes: readonly AdfNode[], path: ConvertErrorPath):
 
 export function tryImageLine(alt: string | undefined, href: string, path: ConvertErrorPath): string | undefined {
   if (alt !== undefined && (/^[ \t]|[ \t]$|[\n\r]/.test(alt) || holdsNullCharacter(alt))) return undefined
-  const destination = spellDestination(href, path)
-  if (!destination.ok) return undefined
+  const destination = spellDestination(href)
+  if (destination === undefined) return undefined
   const description: InlineSegment[] = alt === undefined ? [] : [{ escaping: 'bracketed', text: alt }]
-  const attempt = attemptLine([syntax('!['), ...description, syntax(`](${destination.value})`)], 'paragraph', path)
+  const attempt = attemptLine([syntax('!['), ...description, syntax(`](${destination})`)], 'paragraph', path)
   return attempt.ok ? attempt.value.line : undefined
 }
 
-// A carried node joins no run, so every pass carries at least one more node.
+// A carried node joins no run and the opening link turns directive once, so every pass carries at least one more node.
 function emitLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath): Result<EmittedLine> {
   const carried = new Set<number>()
+  let openingLinkAsDirective = false
   for (;;) {
-    const emission = lineSegments(nodes, container, path, carried)
+    const emission = lineSegments(nodes, container, path, carried, openingLinkAsDirective)
     if (!emission.ok) return emission
     if (emission.value.carry !== undefined) {
       carryRange(carried, emission.value.carry)
@@ -66,8 +77,9 @@ function emitLine(nodes: readonly AdfNode[], container: LineContainer, path: Con
     }
     const attempt = attemptLine(emission.value.segments, container, path)
     if (!attempt.ok) return attempt
-    if (attempt.value.carry === undefined) return success({ line: attempt.value.line, segments: emission.value.segments })
-    carryRange(carried, attempt.value.carry)
+    if (attempt.value.line !== undefined) return success({ line: attempt.value.line, openingLinkAsDirective, segments: emission.value.segments })
+    if (attempt.value.carry !== undefined) carryRange(carried, attempt.value.carry)
+    else openingLinkAsDirective = true
   }
 }
 
@@ -75,8 +87,15 @@ function carryRange(carried: Set<number>, range: NodeRange): void {
   for (let index = range.first; index <= range.last; index += 1) carried.add(index)
 }
 
-function lineSegments(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath, carried: ReadonlySet<number>): Result<Emission> {
-  const emission = emitRun(nodes, 0, 0, { atBlockEnd: true, bracketed: false, carried, path, spansLines: container === 'paragraph' })
+function lineSegments(
+  nodes: readonly AdfNode[],
+  container: LineContainer,
+  path: ConvertErrorPath,
+  carried: ReadonlySet<number>,
+  openingLinkAsDirective: boolean,
+): Result<Emission> {
+  const context: InlineContext = { atBlockEnd: true, bracketed: false, carried, openingLinkAsDirective, path, spansLines: container === 'paragraph' }
+  const emission = emitRun(nodes, 0, 0, context)
   if (!emission.ok) return emission
   if (emission.value.carry !== undefined) return emission
   return success({ segments: carryStrippedWhitespace(emission.value.segments) })
@@ -84,6 +103,7 @@ function lineSegments(nodes: readonly AdfNode[], container: LineContainer, path:
 
 function attemptLine(segments: readonly InlineSegment[], container: LineContainer, path: ConvertErrorPath): Result<LineAttempt> {
   const assembled = assembleInlineLine(segments, container)
+  if (assembled.openingLinkAsDirective) return success({ openingLinkAsDirective: true })
   if (assembled.unspellableRun !== undefined) return success({ carry: assembled.unspellableRun })
   for (const [index, single] of assembled.line.split('\n').entries()) {
     if (container === 'paragraph' && claimsLine(single, index === 0 ? 'first' : 'later')) {
@@ -237,7 +257,13 @@ function emitMarkedRun(nodes: readonly AdfNode[], mark: AdfMark, depth: number,
   if (attributes === undefined) return success({ carry: range })
   if (spelling.kind === 'code') return emitCodeSpan(nodes, depth, range, path)
   if (spelling.kind === 'emphasis') return emitEmphasis(nodes, spelling.spelling, depth, range, context)
-  if (spelling.kind === 'link') return emitLink(nodes, mark, depth, range, context, path)
+  if (spelling.kind === 'link') {
+    const href = nodeAttrs(mark)['href']
+    if (typeof href !== 'string') return success({ carry: range })
+    const opening = depth === 0 && index === 0 && context.openingLinkAsDirective
+    const commonMark = opening ? undefined : commonMarkLink(nodeAttrs(mark), href, isBareLink(nodes, href, depth), context.bracketed)
+    if (commonMark !== undefined) return emitLink(nodes, href, commonMark, depth, range, context)
+  }
   const inner = emitRun(nodes, depth + 1, index, { ...context, bracketed: true, spansLines: false })
   if (!inner.ok) return inner
   if (inner.value.carry !== undefined) return inner
@@ -278,20 +304,17 @@ function needsPadding(text: string): boolean {
   return text.startsWith(' ') && text.endsWith(' ') && /[^ ]/.test(text)
 }
 
-function emitLink(nodes: readonly AdfNode[], mark: AdfMark, depth: number, range: NodeRange, context: InlineContext, path: ConvertErrorPath): Result<Emission> {
-  const href = nodeAttrs(mark)['href']
-  const title = nodeAttrs(mark)['title']
-  if (typeof href !== 'string') return success({ carry: range })
+function isBareLink(nodes: readonly AdfNode[], href: string, depth: number): boolean {
   const node = nodes[0]
-  const bare = nodes.length === 1 && node !== undefined && node.type === 'text' && node.text === href && nodeMarks(node).length === depth + 1
-  const autolinkHolds = !context.bracketed || (!href.includes('`') && !holdsDirectivePrefix(href) && escapeUnbalanced(href, '[', ']') === href)
-  if (bare && autolinkHolds && title === undefined && isAutolink(href) && !holdsEntityReference(href)) return success({ segments: [syntax(`<${href}>`)] })
-  const target = spellLinkTarget(href, typeof title === 'string' ? title : undefined, path)
-  if (!target.ok) return target
+  return nodes.length === 1 && node !== undefined && node.type === 'text' && node.text === href && nodeMarks(node).length === depth + 1
+}
+
+function emitLink(nodes: readonly AdfNode[], href: string, commonMark: CommonMarkLink, depth: number, range: NodeRange, context: InlineContext): Result<Emission> {
+  if (commonMark.form === 'autolink') return success({ segments: [syntax(`<${href}>`)] })
   const inner = emitRun(nodes, depth + 1, range.first, { ...context, bracketed: true })
   if (!inner.ok) return inner
   if (inner.value.carry !== undefined) return inner
-  const spelledTarget: InlineSegment = context.bracketed ? { escaping: 'bracketed-link-target', text: escapeUnbalanced(target.value, '[', ']') } : syntax(target.value)
-  return success({ segments: [{ escaping: 'none', nodes: range, text: '[' }, ...inner.value.segments, syntax(']('), spelledTarget, syntax(')')] })
+  const target: InlineSegment = context.bracketed ? { escaping: 'bracketed-link-target', text: escapeUnbalanced(commonMark.target, '[', ']') } : syntax(commonMark.target)
+  return success({ segments: [{ escaping: 'none', nodes: range, text: '[' }, ...inner.value.segments, syntax(']('), target, syntax(')')] })
 }
 

src/markdown/emit/line-escaping.ts

@@ -17,7 +17,7 @@ export type InlineSegment =
   | { emphasis?: undefined; escaping: 'none'; nodes: NodeRange; text: string }
   | { emphasis?: undefined; escaping: InlineEscaping; nodes?: undefined; text: string }
 
-export type AssembledLine = { line: string; unspellableRun: NodeRange | undefined }
+export type AssembledLine = { line: string; openingLinkAsDirective?: true; unspellableRun: NodeRange | undefined }
 
 type ScanLine = { position: LinePosition; start: number; text: string }
 
@@ -77,8 +77,7 @@ function escape(segments: readonly InlineSegment[], container: LineContainer): A
     output += scan.charAt(index)
   }
   if (container === 'paragraph' && opensLinkDefinition(output)) {
-    const opener = segments[0]?.nodes
-    if (opener !== undefined) return { line: output, unspellableRun: opener }
+    if (segments[0]?.nodes !== undefined) return { line: output, openingLinkAsDirective: true, unspellableRun: undefined }
     return { line: `\\${output}`, unspellableRun: unspellableRun(segments, output, placements) }
   }
   return { line: output, unspellableRun: unspellableRun(segments, output, placements) }

src/markdown/link-syntax.ts

@@ -1,5 +1,4 @@
 import { backslashEscape, decodeTextEscapes, holdsControlCharacter } from './commonmark-grammar.ts'
-import { failure, success, type ConvertErrorPath, type Result } from '../result.ts'
 import { holdsEntityReference } from './entity-references.ts'
 
 export type LinkDefinition = { destination: string; title?: string }
@@ -90,28 +89,17 @@ export function skipLinkWhitespace(text: string, offset: number): number {
   return offset + rest.length - rest.replace(/^[ \t]*\n?[ \t]*/, '').length
 }
 
-export function spellDestination(href: string, path: ConvertErrorPath): Result<string> {
-  if (holdsControlCharacter(href)) return failure('unspellable-link', 'a link destination holds a control character', path)
-  if (href.includes('\\')) return failure('unspellable-link', 'no canonical escape spells a backslash in a link destination', path)
-  if (holdsEntityReference(href)) {
-    return failure('unspellable-link', 'a link destination holds an entity reference that decodes on the way back', path)
-  }
-  if (href.includes(' ')) {
-    if (/[<>]/.test(href)) {
-      return failure('unspellable-link', 'no canonical escape spells an angle bracket beside a space in a link destination', path)
-    }
-    return success(`<${href}>`)
-  }
-  if (href.startsWith('<')) return failure('unspellable-link', 'a bare link destination cannot begin with an angle bracket', path)
-  return success(escapeUnbalanced(href, '(', ')'))
+export function spellDestination(href: string): string | undefined {
+  if (holdsControlCharacter(href) || href.includes('\\') || holdsEntityReference(href)) return undefined
+  if (href.includes(' ')) return /[<>]/.test(href) ? undefined : `<${href}>`
+  return href.startsWith('<') ? undefined : escapeUnbalanced(href, '(', ')')
 }
 
-export function spellLinkTarget(href: string, title: string | undefined, path: ConvertErrorPath): Result<string> {
-  const destination = spellDestination(href, path)
-  if (!destination.ok || title === undefined) return destination
-  const spelledTitle = spellTitle(title, path)
-  if (!spelledTitle.ok) return spelledTitle
-  return success(`${destination.value === '' ? '<>' : destination.value}${spelledTitle.value}`)
+export function spellLinkTarget(href: string, title: string | undefined): string | undefined {
+  const destination = spellDestination(href)
+  if (destination === undefined || title === undefined) return destination
+  const spelledTitle = spellTitle(title)
+  return spelledTitle === undefined ? undefined : `${destination === '' ? '<>' : destination}${spelledTitle}`
 }
 
 export function escapeUnbalanced(spelling: string, opener: string, closer: string): string {
@@ -128,10 +116,6 @@ export function escapeUnbalanced(spelling: string, opener: string, closer: strin
   return spelled
 }
 
-function spellTitle(title: string, path: ConvertErrorPath): Result<string> {
-  if (/[\n\r\\]/.test(title)) {
-    return failure('unspellable-link', 'no canonical escape spells a backslash or newline in a link title', path)
-  }
-  if (holdsEntityReference(title)) return failure('unspellable-link', 'a link title holds an entity reference that decodes on the way back', path)
-  return success(` "${title.replaceAll('"', '\\"')}"`)
+function spellTitle(title: string): string | undefined {
+  return /[\n\r\\]/.test(title) || holdsEntityReference(title) ? undefined : ` "${title.replaceAll('"', '\\"')}"`
 }

src/markdown/mark-spellings.ts

@@ -1,15 +1,20 @@
-import type { AdfMark } from '../adf/document.ts'
+import type { AdfAttributes, AdfMark } from '../adf/document.ts'
 import type { AttributeVocabulary } from '../adf/attribute-vocabulary.ts'
 import type { MarkType } from '../adf/mark-attributes.ts'
+import { escapeUnbalanced, spellLinkTarget } from './link-syntax.ts'
+import { holdsDirectivePrefix, spellAttributes, spellVocabulary } from './directive-syntax.ts'
+import { holdsEntityReference } from './entity-references.ts'
+import { isAutolink } from './commonmark-grammar.ts'
 import { isMarkType, markAttributes } from '../adf/mark-attributes.ts'
 import { nodeAttrs } from '../adf/document.ts'
-import { spellAttributes, spellVocabulary } from './directive-syntax.ts'
 import { vocabularyPairs } from '../adf/attribute-vocabulary.ts'
 
 type Spelling = { kind: 'code' | 'directive' | 'link'; spelling?: undefined } | { kind: 'emphasis'; spelling: string }
 
 export type MarkSpelling = Spelling & { attributes: AttributeVocabulary }
 
+export type CommonMarkLink = { form: 'autolink'; target?: undefined } | { form: 'inline'; target: string }
+
 const markSpellings: Readonly<Record<MarkType, Spelling>> = {
   border: { kind: 'directive' },
   code: { kind: 'code' },
@@ -30,6 +35,16 @@ export function markSpelling(type: string): MarkSpelling | undefined {
   return { attributes, kind: spelling.kind }
 }
 
+// spec/flavour.md, Marks. `bare`: one text node reading exactly `href`, the link innermost.
+export function commonMarkLink(attrs: AdfAttributes, href: string, bare: boolean, bracketed: boolean): CommonMarkLink | undefined {
+  if (Object.keys(attrs).some((key) => key !== 'href' && key !== 'title')) return undefined
+  const title = attrs['title']
+  const autolinkHolds = !bracketed || (!href.includes('`') && !holdsDirectivePrefix(href) && escapeUnbalanced(href, '[', ']') === href)
+  if (bare && autolinkHolds && title === undefined && isAutolink(href) && !holdsEntityReference(href)) return { form: 'autolink' }
+  const target = spellLinkTarget(href, typeof title === 'string' ? title : undefined)
+  return target === undefined ? undefined : { form: 'inline', target }
+}
+
 export function spellMarkAttributes(mark: AdfMark, vocabulary: AttributeVocabulary): string | undefined {
   const pairs = vocabularyPairs(nodeAttrs(mark), vocabulary, [])
   return pairs === undefined ? undefined : spellAttributes(spellVocabulary(pairs))

src/markdown/parse/directive-marks.ts

@@ -28,10 +28,9 @@ function markdownForm(spelling: MarkSpelling): string | undefined {
     case 'code':
       return '`x`'
     case 'directive':
+    case 'link':
       return undefined
     case 'emphasis':
       return `${spelling.spelling}x${spelling.spelling}`
-    case 'link':
-      return '[x](url)'
   }
 }

src/markdown/parse/inline-content.ts

@@ -1,15 +1,18 @@
 import type { AdfMark, AdfNode } from '../../adf/document.ts'
 import type { DirectiveSpan } from '../directive-syntax.ts'
 import type { EmphasisPairing } from '../emphasis-matching.ts'
+import type { LineContainer } from '../emit/line-escaping.ts'
 import type { LinkDefinition } from '../link-syntax.ts'
 import { backslashEscape, decodeTextEscapes, inlineHtmlConstruct, readBracketedAutolink, readEmailAutolink, trimTrailingSpace } from '../commonmark-grammar.ts'
 import { backtickRun, closingBacktickRun } from '../backtick-runs.ts'
+import { commonMarkLink } from '../mark-spellings.ts'
 import { delimiterFlags, matchEmphasis, runLength } from '../emphasis-matching.ts'
 import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts'
 import { inlineDirective } from '../../adf/inline-directives.ts'
 import { mergeAdjacentText } from '../../adf/editor-normal.ts'
 import { nodeAttrs, nodeMarks } from '../../adf/document.ts'
 import { normalizeLabel, readInlineTarget, readLabel } from '../link-syntax.ts'
+import { openingLinkTakesDirective } from '../emit/inline-line.ts'
 import { readCarriedInline } from '../opaque-carry.ts'
 import { readDirectiveMark } from './directive-marks.ts'
 import { readInlineDirective } from '../directive-syntax.ts'
@@ -33,19 +36,29 @@ type Piece =
 
 type Run = { canClose: boolean; canOpen: boolean; character: string; index: number; length: number }
 
-type Scan = { definitions: LinkDefinitions; path: ConvertErrorPath; pending: string; pieces: Piece[]; source: string }
+// `container` is the emitter's line container, `undefined` inside a directive's content slot; `openingSpellableLink` defers a directive link at offset 0 to `assemble`.
+type Scan = {
+  container: LineContainer | undefined
+  definitions: LinkDefinitions
+  openingSpellableLink: boolean
+  path: ConvertErrorPath
+  pending: string
+  pieces: Piece[]
+  source: string
+}
 
 type SlotContent = { carry: boolean; nodes: AdfNode[] }
 
 const carriedInMark = 'no mark spelling wraps an opaque carry: the carried node restores exactly, marks included'
 const imageAlone = 'an image fits only as a paragraph of its own: this one sits inside other content'
+const spellableLink = 'link takes the directive form only where CommonMark cannot spell it: this one it can'
 
-export function parseInlineContent(source: string, definitions: LinkDefinitions, path: ConvertErrorPath): Result<InlineContent> {
-  return parseInline(source, definitions, path, true)
+export function parseInlineContent(source: string, definitions: LinkDefinitions, path: ConvertErrorPath, container: LineContainer): Result<InlineContent> {
+  return parseInline(source, definitions, path, container)
 }
 
-function parseInline(source: string, definitions: LinkDefinitions, path: ConvertErrorPath, strip: boolean): Result<InlineContent> {
-  const scan: Scan = { definitions, path, pending: '', pieces: [], source }
+function parseInline(source: string, definitions: LinkDefinitions, path: ConvertErrorPath, container: LineContainer | undefined): Result<InlineContent> {
+  const scan: Scan = { container, definitions, openingSpellableLink: false, path, pending: '', pieces: [], source }
   let index = 0
   while (index < source.length) {
     switch (source.charAt(index)) {
@@ -93,7 +106,7 @@ function parseInline(source: string, definitions: LinkDefinitions, path: Convert
         index += 1
     }
   }
-  flush(scan, strip)
+  flush(scan, container !== undefined)
   return assemble(scan)
 }
 
@@ -158,14 +171,14 @@ function readDirective(scan: Scan, index: number): Result<number> | undefined {
   const directive = readInlineDirective(scan.source, index)
   if (directive === undefined) return undefined
   if (directive.fault !== undefined) return faulted(directive.fault, scan.path)
-  const piece = directivePiece(scan, directive.value)
+  const piece = directivePiece(scan, directive.value, index)
   if (!piece.ok) return piece
   flush(scan, false)
   scan.pieces.push(piece.value)
   return success(index + directive.value.length)
 }
 
-function directivePiece(scan: Scan, span: DirectiveSpan): Result<Piece> {
+function directivePiece(scan: Scan, span: DirectiveSpan, index: number): Result<Piece> {
   const carried = readCarriedInline(span)
   if (carried !== undefined) {
     if (carried.fault !== undefined) return faulted(carried.fault, scan.path)
@@ -183,6 +196,8 @@ function directivePiece(scan: Scan, span: DirectiveSpan): Result<Piece> {
       return failure('unsupported-node-shape', `the ${span.name} mark wraps the [content] it marks: this one wraps none`, scan.path)
     }
     if (slot.value.carry) return failure('unsupported-node-shape', carriedInMark, scan.path)
+    const refused = mark.value.type === 'link' ? refuseSpellableLink(scan, mark.value, slot.value.nodes, index) : undefined
+    if (refused !== undefined) return refused
     return success({ kind: 'nodes', nodes: applyMark(slot.value.nodes, mark.value) })
   }
   const node = readInlineDirectiveNode(span.name, span.attributes, slot.value?.nodes, scan.path)
@@ -190,9 +205,21 @@ function directivePiece(scan: Scan, span: DirectiveSpan): Result<Piece> {
   return success({ kind: 'nodes', nodes: [node.value] })
 }
 
+// spec/flavour.md, Marks. A link opening a paragraph may still need the directive form for the line it opens, which `assemble` asks the emitter.
+function refuseSpellableLink(scan: Scan, mark: AdfMark, nodes: readonly AdfNode[], index: number): Result<Piece> | undefined {
+  const href = nodeAttrs(mark)['href']
+  if (typeof href !== 'string') return undefined
+  const only = nodes[0]
+  const bare = nodes.length === 1 && only !== undefined && only.type === 'text' && only.text === href && nodeMarks(only).length === 0
+  if (commonMarkLink(nodeAttrs(mark), href, bare, scan.container === undefined) === undefined) return undefined
+  if (index !== 0 || scan.container !== 'paragraph') return failure('unsupported-node-shape', spellableLink, scan.path)
+  scan.openingSpellableLink = true
+  return undefined
+}
+
 function slotContent(scan: Scan, content: string | undefined): Result<SlotContent | undefined> {
   if (content === undefined) return success(undefined)
-  const parsed = parseInline(content, scan.definitions, scan.path, false)
+  const parsed = parseInline(content, scan.definitions, scan.path, undefined)
   if (!parsed.ok) return parsed
   if (parsed.value.image !== undefined) return failure('unmappable-image', imageAlone, scan.path)
   return success(parsed.value)
@@ -214,6 +241,11 @@ function assemble(scan: Scan): Result<InlineContent> {
   if (holdsImage(scan.pieces)) return failure('unmappable-image', imageAlone, scan.path)
   const nodes = resolveNodes(scan.pieces, scan.path)
   if (!nodes.ok) return nodes
+  if (scan.openingSpellableLink) {
+    const takesDirective = openingLinkTakesDirective(nodes.value, scan.path)
+    if (!takesDirective.ok) return takesDirective
+    if (!takesDirective.value) return failure('unsupported-node-shape', spellableLink, scan.path)
+  }
   return success({ carry: holdsCarry(scan.pieces), nodes: nodes.value })
 }
 

src/markdown/parse/markdown-to-adf.test.ts

@@ -287,8 +287,8 @@ test('names the directive form a node CommonMark spells refuses', () => {
 
 // The spelling the emitter refuses gives the emitter's own error, never a second name for it.
 test('gives back the refusal the CommonMark spelling itself raises', () => {
-  const destination = '!adf:blockquote\n[t](https://example.com/a\\b)\n!adf:/blockquote\n'
-  assert.equal(content(markdownToAdf(destination)), 'unspellable-link: no canonical escape spells a backslash in a link destination')
+  const lineStart = '!adf:blockquote\n` `` `\n!adf:/blockquote\n'
+  assert.equal(content(markdownToAdf(lineStart)), 'unspellable-line-start: block parsing would claim the emitted line "``` `` ```"')
 })
 
 test('names the directive name no node reads back to', () => {
@@ -966,7 +966,25 @@ test('names the mark markdown spells, never a directive', () => {
   assert.equal(content(markdownToAdf('!adf:strong[a]\n')), 'unsupported-node-shape: strong is spelled **x**, never as a directive')
   assert.equal(content(markdownToAdf('!adf:strike[a]\n')), 'unsupported-node-shape: strike is spelled ~~x~~, never as a directive')
   assert.equal(content(markdownToAdf('!adf:code[a]\n')), 'unsupported-node-shape: code is spelled `x`, never as a directive')
-  assert.equal(content(markdownToAdf('!adf:link[a]{href="/u"}\n')), 'unsupported-node-shape: link is spelled [x](url), never as a directive')
+})
+
+// spec/flavour.md, Marks: the directive link is refused wherever the emitter would pick the markdown spelling.
+test('refuses the directive link CommonMark could spell, and reads the one it could not', () => {
+  const refused = 'unsupported-node-shape: link takes the directive form only where CommonMark cannot spell it: this one it can'
+  assert.equal(content(markdownToAdf('!adf:link[a]{href="/u"}\n')), refused)
+  assert.equal(content(markdownToAdf('See !adf:link[a]{href="/u"}.\n')), refused)
+  assert.equal(content(markdownToAdf('!adf:link[https://example.com/]{href="https://example.com/"}\n')), refused)
+  assert.equal(content(markdownToAdf('# !adf:link[`]: a`]{href="/u"}\n')), refused)
+  assert.equal(content(markdownToAdf('| !adf:link[`]: a`]{href="/u"} |\n| --- |\n')), refused)
+  assert.equal(content(markdownToAdf('!adf:underline[!adf:link[a]{href="/u"}]\n')), refused)
+  assert.deepEqual(path(markdownToAdf('Part.\n\nSee !adf:link[a]{href="/u"}.\n')), ['content', 1])
+  const titled: AdfNode = { marks: [{ attrs: { title: 't' }, type: 'link' }], text: 'a', type: 'text' }
+  assert.deepEqual(content(markdownToAdf('!adf:link[a]{title=t}\n')), [{ content: [titled], type: 'paragraph' }])
+  const opening: AdfNode = { marks: [{ attrs: { href: '/u' }, type: 'link' }, { type: 'code' }], text: ']: a', type: 'text' }
+  assert.deepEqual(content(markdownToAdf('!adf:link[`]: a`]{href="/u"}\n')), [{ content: [opening], type: 'paragraph' }])
+  assert.deepEqual(content(markdownToAdf('!adf:heading {level=1 localId=h}\n!adf:link[`]: a`]{href="/u"}\n!adf:/heading\n')), [
+    { attrs: { level: 1, localId: 'h' }, content: [opening], type: 'heading' },
+  ])
 })
 
 test('names the directive mark left without the content it wraps', () => {

src/markdown/parse/markdown-to-adf.ts

@@ -2,6 +2,7 @@ import type { AdfDocument, AdfNode } from '../../adf/document.ts'
 import type { Block, DirectiveBlock } from './blocks.ts'
 import type { BlockDirectiveNode } from './directive-nodes.ts'
 import type { ConvertFault } from '../../result.ts'
+import type { LineContainer } from '../emit/line-escaping.ts'
 import type { LinkDefinitions } from './inline-content.ts'
 import { carryName, readCarriedBlock } from '../opaque-carry.ts'
 import { commonMarkSpelling } from '../emit/adf-to-markdown.ts'
@@ -67,7 +68,7 @@ function blockNode(block: Block, definitions: LinkDefinitions, path: ConvertErro
     case 'fault':
       return faulted(block.fault, path)
     case 'heading':
-      return contentNode({ attrs: { level: block.level }, type: 'heading' }, block.text, definitions, path)
+      return contentNode({ attrs: { level: block.level }, type: 'heading' }, block.text, definitions, path, 'heading')
     case 'html':
       return failure('unmappable-html', `no raw HTML converts at this version: ${block.construct}`, path)
     case 'orderedList':
@@ -119,7 +120,7 @@ function tableNode(rows: readonly string[][], definitions: LinkDefinitions, path
     const type = rowIndex === 0 ? 'tableHeader' : 'tableCell'
     const row: AdfNode[] = []
     for (const [cellIndex, cell] of cells.entries()) {
-      const paragraph = contentNode({ type: 'paragraph' }, cell, definitions, [...path, 'content', rowIndex, 'content', cellIndex, 'content', 0])
+      const paragraph = contentNode({ type: 'paragraph' }, cell, definitions, [...path, 'content', rowIndex, 'content', cellIndex, 'content', 0], 'table-cell')
       if (!paragraph.ok) return paragraph
       row.push({ content: [paragraph.value], type })
     }
@@ -133,7 +134,7 @@ function inlineBodyNode(node: AdfNode, blocks: readonly Block[], definitions: Li
   const only = blocks.length === 1 ? blocks[0] : undefined
   if (only?.kind === 'fault') return positioned(faulted(only.fault, path), only.position)
   if (only?.kind !== 'paragraph') return failure('unsupported-node-shape', `${node.type} takes one paragraph as its body: this body is not one`, path)
-  return positioned(contentNode(node, only.text, definitions, path), only.position)
+  return positioned(contentNode(node, only.text, definitions, path, 'paragraph'), only.position)
 }
 
 function containerNode(node: AdfNode, blocks: readonly Block[], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number): Result<AdfNode> {
@@ -168,14 +169,14 @@ function codeBlockNode(language: string, text: string, path: ConvertErrorPath, d
 
 // spec/flavour.md, The CommonMark image: only a plain paragraph gives an image the block it needs.
 function paragraphNode(text: string, definitions: LinkDefinitions, path: ConvertErrorPath): Result<AdfNode> {
-  const content = parseInlineContent(text, definitions, path)
+  const content = parseInlineContent(text, definitions, path, 'paragraph')
   if (!content.ok) return content
   const image = content.value.image
   return success(image === undefined ? withContent({ type: 'paragraph' }, content.value.nodes) : image)
 }
 
-function contentNode(node: AdfNode, text: string, definitions: LinkDefinitions, path: ConvertErrorPath): Result<AdfNode> {
-  const content = parseInlineContent(text, definitions, path)
+function contentNode(node: AdfNode, text: string, definitions: LinkDefinitions, path: ConvertErrorPath, container: LineContainer): Result<AdfNode> {
+  const content = parseInlineContent(text, definitions, path, container)
   if (!content.ok) return content
   if (content.value.image !== undefined) return failure('unmappable-image', `no ADF node carries an image inside a ${node.type}`, path)
   return success(withContent(node, content.value.nodes))

src/result.ts

@@ -7,7 +7,6 @@ export type ConvertErrorCode =
   | 'unmappable-image'
   | 'unspellable-character'
   | 'unspellable-line-start'
-  | 'unspellable-link'
   | 'unspellable-whitespace'
   | 'unsupported-document-version'
   | 'unsupported-nesting-depth'