Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| e8733068ab | |||
| 2f0ab4dda9 | |||
| 9f23c89719 | |||
| 58a9c89dfc |
@@ -54,6 +54,7 @@ In `docs/decisions.md`:
|
|||||||
- The flavour spec is read as a source
|
- The flavour spec is read as a source
|
||||||
- The node tables answer to Atlassian's schema
|
- The node tables answer to Atlassian's schema
|
||||||
- Nothing recurses unbounded
|
- Nothing recurses unbounded
|
||||||
|
- No value `JSON.parse` or `structuredClone` builds loops a call
|
||||||
- Nothing spreads an unbounded array
|
- Nothing spreads an unbounded array
|
||||||
- A retry loop checks its own termination
|
- A retry loop checks its own termination
|
||||||
- Readers scan by index
|
- Readers scan by index
|
||||||
|
|||||||
+1
-3
@@ -32,9 +32,7 @@
|
|||||||
- Fix an image inside another image's description: it flattens into the alt text, where it was
|
- Fix an image inside another image's description: it flattens into the alt text, where it was
|
||||||
refused.
|
refused.
|
||||||
- Fix a cyclic document, in which an object holds itself: `adfToMarkdown` and `adfToPlainMarkdown`
|
- Fix a cyclic document, in which an object holds itself: `adfToMarkdown` and `adfToPlainMarkdown`
|
||||||
refuse it as `not-an-adf-document` and `isAdfDocument` returns `false`, where all three hung. A
|
refuse it as `not-an-adf-document` and `isAdfDocument` returns `false`, where all three hung.
|
||||||
node or mark whose `attrs`, `content`, `marks`, `text` or `type` is not its own enumerable key is
|
|
||||||
refused alike, where it was read.
|
|
||||||
|
|
||||||
## 0.1.0
|
## 0.1.0
|
||||||
|
|
||||||
|
|||||||
@@ -33,7 +33,7 @@ The most useful ADF conversion library available, judged by these goals, in prio
|
|||||||
5. **No surprises: output reads and edits the way its audience expects.**
|
5. **No surprises: output reads and edits the way its audience expects.**
|
||||||
6. **Lossy conversion drops form, never content.**
|
6. **Lossy conversion drops form, never content.**
|
||||||
7. **Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.**
|
7. **Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.**
|
||||||
8. **Fast, and linear in the document's size.**
|
8. **Fast, and linear in the document's size as JSON.**
|
||||||
9. **Easy to find, and clear at a glance what it does.**
|
9. **Easy to find, and clear at a glance what it does.**
|
||||||
|
|
||||||
## Audience
|
## Audience
|
||||||
@@ -238,8 +238,8 @@ Serves Goals 1, 3 and 4.
|
|||||||
input.
|
input.
|
||||||
- Past that and `~~`, no GFM: an autolink literal and a `- [ ]` marker stay text, and a checklist
|
- Past that and `~~`, no GFM: an autolink literal and a `- [ ]` marker stay text, and a checklist
|
||||||
is the `taskList` directive — `plainMarkdownToAdf` turns the marker into a `taskList`.
|
is the `taskList` directive — `plainMarkdownToAdf` turns the marker into a `taskList`.
|
||||||
- A document nested deeper than 500 levels is an error result, not a stack overflow, and no input
|
- A document nested deeper than 500 levels is an error result, not a stack overflow, and no call
|
||||||
makes a call loop forever.
|
loops forever on a string, or on a value `JSON.parse` or `structuredClone` builds.
|
||||||
- The emitted formats are semver surface
|
- The emitted formats are semver surface
|
||||||
([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#the-formats-are-api)).
|
([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#the-formats-are-api)).
|
||||||
- **`0.2.0`** — `htmlToAdf(adfToHtml(doc))` deep-equals `doc`; fidelity HTML cannot express rides
|
- **`0.2.0`** — `htmlToAdf(adfToHtml(doc))` deep-equals `doc`; fidelity HTML cannot express rides
|
||||||
|
|||||||
@@ -563,6 +563,15 @@ format, as its parser does. A list giving way to the directive form refuses at z
|
|||||||
than walking again; counting every list twice halved the list limit, counting the directive form
|
than walking again; counting every list twice halved the list limit, counting the directive form
|
||||||
once doubled the parser's frames per level.
|
once doubled the parser's frames per level.
|
||||||
|
|
||||||
|
## No value `JSON.parse` or `structuredClone` builds loops a call
|
||||||
|
|
||||||
|
2026-10-04, the maintainer. Goals 1 and 8. Valid while every persona hands in plain data, as
|
||||||
|
`JSON.parse` or `structuredClone` builds it.
|
||||||
|
|
||||||
|
The guards walk a value by `Object.values` and refuse a cycle in it. An inherited or non-enumerable
|
||||||
|
key, a getter, a Proxy or a custom iterator is the caller's to rule out: no persona builds one.
|
||||||
|
Goal 8's size counts ADF as JSON, so a shared object costs once per place it is held.
|
||||||
|
|
||||||
## Nothing spreads an unbounded array
|
## Nothing spreads an unbounded array
|
||||||
|
|
||||||
2026-09-18, the maintainer. Goal 1. Valid while engines cap a call's arguments.
|
2026-09-18, the maintainer. Goal 1. Valid while engines cap a call's arguments.
|
||||||
|
|||||||
@@ -83,7 +83,7 @@ test("reads a node's siblings as a walk rather than as one call's arguments", ()
|
|||||||
assert.equal(fault(wide), 'accepted')
|
assert.equal(fault(wide), 'accepted')
|
||||||
})
|
})
|
||||||
|
|
||||||
test('refuses an object holding itself or a key it does not own, and accepts one shared', () => {
|
test('refuses an object holding itself, and accepts one shared', () => {
|
||||||
const holdsItself = 'an ADF document is a tree: an object in it holds itself'
|
const holdsItself = 'an ADF document is a tree: an object in it holds itself'
|
||||||
const paragraph: { content: unknown[]; type: string } = { content: [], type: 'paragraph' }
|
const paragraph: { content: unknown[]; type: string } = { content: [], type: 'paragraph' }
|
||||||
paragraph.content.push(paragraph)
|
paragraph.content.push(paragraph)
|
||||||
@@ -96,26 +96,6 @@ test('refuses an object holding itself or a key it does not own, and accepts one
|
|||||||
assert.equal(fault({ content: [{ attrs, type: 'paragraph' }], type: 'doc', version: 1 }), holdsItself)
|
assert.equal(fault({ content: [{ attrs, type: 'paragraph' }], type: 'doc', version: 1 }), holdsItself)
|
||||||
assert.equal(fault({ content: [{ marks: [{ attrs, type: 'link' }], text: 'x', type: 'text' }], type: 'doc', version: 1 }), holdsItself)
|
assert.equal(fault({ content: [{ marks: [{ attrs, type: 'link' }], text: 'x', type: 'text' }], type: 'doc', version: 1 }), holdsItself)
|
||||||
assert.equal(isAdfDocument({ content: [{ attrs, type: 'paragraph' }], type: 'doc', version: 1 }), false)
|
assert.equal(isAdfDocument({ content: [{ attrs, type: 'paragraph' }], type: 'doc', version: 1 }), false)
|
||||||
const notANode = "an ADF document's content holds ADF nodes: one of them is not"
|
|
||||||
const inherits: { content?: unknown[] } = {}
|
|
||||||
const heir: Record<string, unknown> = Object.create(inherits)
|
|
||||||
heir['type'] = 'paragraph'
|
|
||||||
inherits.content = [heir]
|
|
||||||
assert.equal(fault({ content: [heir], type: 'doc', version: 1 }), notANode)
|
|
||||||
const hidden: Record<string, unknown> = { type: 'paragraph' }
|
|
||||||
Object.defineProperty(hidden, 'content', { value: [hidden] })
|
|
||||||
assert.equal(fault({ content: [hidden], type: 'doc', version: 1 }), notANode)
|
|
||||||
const link: Record<string, unknown> = Object.create({ attrs })
|
|
||||||
link['type'] = 'link'
|
|
||||||
assert.equal(fault({ content: [{ marks: [link], text: 'x', type: 'text' }], type: 'doc', version: 1 }), notANode)
|
|
||||||
const indexed: unknown[] = []
|
|
||||||
Object.defineProperty(indexed, 0, { value: indexed })
|
|
||||||
assert.equal(fault({ content: [{ attrs: { a: indexed }, type: 'paragraph' }], type: 'doc', version: 1 }), holdsItself)
|
|
||||||
const inheritedIndex: { content?: unknown[]; type: string } = { type: 'paragraph' }
|
|
||||||
const heirs: unknown[] = Object.setPrototypeOf([], [inheritedIndex])
|
|
||||||
heirs.length = 1
|
|
||||||
inheritedIndex.content = heirs
|
|
||||||
assert.equal(fault({ content: [inheritedIndex], type: 'doc', version: 1 }), holdsItself)
|
|
||||||
const bold = { type: 'strong' }
|
const bold = { type: 'strong' }
|
||||||
const text = { marks: [bold], text: 'x', type: 'text' }
|
const text = { marks: [bold], text: 'x', type: 'text' }
|
||||||
const shared = { content: [text, text], type: 'paragraph' }
|
const shared = { content: [text, text], type: 'paragraph' }
|
||||||
|
|||||||
+3
-8
@@ -106,7 +106,7 @@ export function isAdfNode(value: unknown): value is AdfNode {
|
|||||||
}
|
}
|
||||||
|
|
||||||
export function isAdfMark(value: unknown): value is AdfMark {
|
export function isAdfMark(value: unknown): value is AdfMark {
|
||||||
if (!isRecord(value) || !holdsOnly(value, markKeys) || !ownsWhatItHolds(value, markKeys)) return false
|
if (!isRecord(value) || !holdsOnly(value, markKeys)) return false
|
||||||
if (typeof value['type'] !== 'string') return false
|
if (typeof value['type'] !== 'string') return false
|
||||||
return !('attrs' in value) || isAttributes(value['attrs'])
|
return !('attrs' in value) || isAttributes(value['attrs'])
|
||||||
}
|
}
|
||||||
@@ -135,7 +135,7 @@ function holdsItself(root: object): boolean {
|
|||||||
if (onPath.has(entry.item)) return true
|
if (onPath.has(entry.item)) return true
|
||||||
ancestors.push(entry.item)
|
ancestors.push(entry.item)
|
||||||
onPath.add(entry.item)
|
onPath.add(entry.item)
|
||||||
for (const child of Array.isArray(entry.item) ? [...entry.item] : Object.values(entry.item)) if (typeof child === 'object' && child !== null) pending.push({ depth: entry.depth + 1, item: child })
|
for (const child of Object.values(entry.item)) if (typeof child === 'object' && child !== null) pending.push({ depth: entry.depth + 1, item: child })
|
||||||
}
|
}
|
||||||
return false
|
return false
|
||||||
}
|
}
|
||||||
@@ -144,7 +144,7 @@ function isNodeArray(value: readonly unknown[]): value is readonly AdfNode[] {
|
|||||||
const pending: unknown[] = [...value]
|
const pending: unknown[] = [...value]
|
||||||
while (pending.length > 0) {
|
while (pending.length > 0) {
|
||||||
const node = pending.pop()
|
const node = pending.pop()
|
||||||
if (!isRecord(node) || !holdsOnly(node, nodeKeys) || !ownsWhatItHolds(node, nodeKeys)) return false
|
if (!isRecord(node) || !holdsOnly(node, nodeKeys)) return false
|
||||||
if (typeof node['type'] !== 'string') return false
|
if (typeof node['type'] !== 'string') return false
|
||||||
if ('attrs' in node && !isAttributes(node['attrs'])) return false
|
if ('attrs' in node && !isAttributes(node['attrs'])) return false
|
||||||
if ('marks' in node && !isArrayOf(node['marks'], isAdfMark)) return false
|
if ('marks' in node && !isArrayOf(node['marks'], isAdfMark)) return false
|
||||||
@@ -219,11 +219,6 @@ function extraKey(value: Record<string, unknown>, keys: readonly string[]): stri
|
|||||||
return Object.keys(value).find((key) => !keys.includes(key))
|
return Object.keys(value).find((key) => !keys.includes(key))
|
||||||
}
|
}
|
||||||
|
|
||||||
// holdsItself walks own enumerable keys alone, so a guard reading any other key could walk a cycle forever.
|
|
||||||
function ownsWhatItHolds(value: Record<string, unknown>, keys: readonly string[]): boolean {
|
|
||||||
return keys.every((key) => !(key in value) || Object.prototype.propertyIsEnumerable.call(value, key))
|
|
||||||
}
|
|
||||||
|
|
||||||
function holdsOnly(value: Record<string, unknown>, keys: readonly string[]): boolean {
|
function holdsOnly(value: Record<string, unknown>, keys: readonly string[]): boolean {
|
||||||
return extraKey(value, keys) === undefined
|
return extraKey(value, keys) === undefined
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -6,7 +6,7 @@
|
|||||||
|
|
||||||
`Bar = 9`
|
`Bar = 9`
|
||||||
|
|
||||||
`Next ID = 66`
|
`Next ID = 67`
|
||||||
|
|
||||||
| Goal | W |
|
| Goal | W |
|
||||||
|---|---|
|
|---|---|
|
||||||
@@ -29,6 +29,7 @@
|
|||||||
| 45 | 0.2.0 | | **Replace `isAdfDocument` with a reader returning `Result<AdfDocument>`.** | 2 | 3 | 6 | 8 | 1 | 25.2 |
|
| 45 | 0.2.0 | | **Replace `isAdfDocument` with a reader returning `Result<AdfDocument>`.** | 2 | 3 | 6 | 8 | 1 | 25.2 |
|
||||||
| 6 | 0.2.0 | decision | **Specify the HTML dialect.** | 2 | 6 | 7 | 8 | 2, 3 | 24.7 |
|
| 6 | 0.2.0 | decision | **Specify the HTML dialect.** | 2 | 6 | 7 | 8 | 2, 3 | 24.7 |
|
||||||
| 64 | 0.2.0 | defect | **Read back unchanged on V8 every JSON key the emitter writes, with a fixture whose key holds `\`, `"` or a control character.** | 4 | 4 | 6 | 8 | 1, 7 | 23.0 |
|
| 64 | 0.2.0 | defect | **Read back unchanged on V8 every JSON key the emitter writes, with a fixture whose key holds `\`, `"` or a control character.** | 4 | 4 | 6 | 8 | 1, 7 | 23.0 |
|
||||||
|
| 66 | 0.2.0 | | **Refuse an attribute value that is not a plain object, array or JSON primitive.** | 3 | 2 | 5 | 8 | 1 | 22.5 |
|
||||||
| 43 | 0.2.0 | decision | **Give each markdown input its own reader, strict to its own standard.** | 6 | 7 | 8 | 9 | 3, 4 | 22.3 |
|
| 43 | 0.2.0 | decision | **Give each markdown input its own reader, strict to its own standard.** | 6 | 7 | 8 | 9 | 3, 4 | 22.3 |
|
||||||
| 65 | 0.2.0 | defect | **Read an image not alone in its paragraph as its alt text linked to its URL, and a titled image alone in its paragraph as the image captioned with its title.** | 5 | 5 | 7 | 7 | 3, 4, 6 | 18.7 |
|
| 65 | 0.2.0 | defect | **Read an image not alone in its paragraph as its alt text linked to its URL, and a titled image alone in its paragraph as the image captioned with its title.** | 5 | 5 | 7 | 7 | 3, 4, 6 | 18.7 |
|
||||||
| 49 | 0.2.0 | | **Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`.** | 4 | 5 | 5 | 8 | 3, 4 | 17.2 |
|
| 49 | 0.2.0 | | **Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`.** | 4 | 5 | 5 | 8 | 3, 4 | 17.2 |
|
||||||
@@ -101,6 +102,13 @@ Deno and Chrome the round-trip would refuse its own output or read back a differ
|
|||||||
tells which. Confirm with a fixture first; then read JSON with our own parser or record the gap with
|
tells which. Confirm with a fixture first; then read JSON with our own parser or record the gap with
|
||||||
an ending item. Found by the README-goals audit, 2026-10-03.
|
an ending item. Found by the README-goals audit, 2026-10-03.
|
||||||
|
|
||||||
|
### 66. Refuse an attribute value that is not a plain object, array or JSON primitive.
|
||||||
|
|
||||||
|
`isJsonValue` (`json-value.ts`) walks any object by `Object.values`, so a `Date`, `Map`, `Set` or
|
||||||
|
typed array in `attrs`, as `structuredClone` keeps it, passes the guard and is written as `{}` or a
|
||||||
|
key per element: `ok: true` with content lost. Accept an object whose prototype is
|
||||||
|
`Object.prototype` or `null`, and an array. Found by the stability review of item 63, 2026-10-04.
|
||||||
|
|
||||||
### 43. Give each markdown input its own reader, strict to its own standard.
|
### 43. Give each markdown input its own reader, strict to its own standard.
|
||||||
|
|
||||||
Today `markdownToAdf` reads CommonMark and the lossless flavour as one input: text shaped like a
|
Today `markdownToAdf` reads CommonMark and the lossless flavour as one input: text shaped like a
|
||||||
|
|||||||
Reference in New Issue
Block a user