diff --git a/AGENTS.md b/AGENTS.md index 614fcc0..504edfd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,6 +54,7 @@ In `docs/decisions.md`: - The flavour spec is read as a source - The node tables answer to Atlassian's schema - Nothing recurses unbounded +- The guards take what `JSON.parse` or `structuredClone` builds - Nothing spreads an unbounded array - A retry loop checks its own termination - Readers scan by index diff --git a/CHANGELOG.md b/CHANGELOG.md index 791878c..5e1c5cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,9 +32,7 @@ - Fix an image inside another image's description: it flattens into the alt text, where it was refused. - 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 - node or mark whose `attrs`, `content`, `marks`, `text` or `type` is not its own enumerable key is - refused alike, where it was read. + refuse it as `not-an-adf-document` and `isAdfDocument` returns `false`, where all three hung. ## 0.1.0 diff --git a/README.md b/README.md index 71cde23..3137576 100644 --- a/README.md +++ b/README.md @@ -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.** 6. **Lossy conversion drops form, never content.** 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.** ## Audience @@ -238,8 +238,8 @@ Serves Goals 1, 3 and 4. input. - 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`. -- A document nested deeper than 500 levels is an error result, not a stack overflow, and no input - makes a call loop forever. +- A document nested deeper than 500 levels is an error result, not a stack overflow, and no value + `JSON.parse` or `structuredClone` builds makes a call loop forever. - 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)). - **`0.2.0`** — `htmlToAdf(adfToHtml(doc))` deep-equals `doc`; fidelity HTML cannot express rides diff --git a/docs/decisions.md b/docs/decisions.md index 415f3a2..5ca97cd 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -563,6 +563,16 @@ 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 once doubled the parser's frames per level. +## The guards take what `JSON.parse` or `structuredClone` builds + +2026-10-04, the maintainer. Goal 1. Valid while every persona hands in a value `JSON.parse`, +`structuredClone` or an object literal builds. + +The guarantees speak of plain data: own enumerable keys and plain arrays, cycles and shared objects +included. The guards walk it by `Object.values` and refuse a cycle. 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, and +each guarded shape asked for another. + ## Nothing spreads an unbounded array 2026-09-18, the maintainer. Goal 1. Valid while engines cap a call's arguments. diff --git a/src/adf/document.test.ts b/src/adf/document.test.ts index 1a876fb..5b66c8f 100644 --- a/src/adf/document.test.ts +++ b/src/adf/document.test.ts @@ -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') }) -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 paragraph: { content: unknown[]; type: string } = { content: [], type: '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: [{ 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) - const notANode = "an ADF document's content holds ADF nodes: one of them is not" - const inherits: { content?: unknown[] } = {} - const heir: Record = Object.create(inherits) - heir['type'] = 'paragraph' - inherits.content = [heir] - assert.equal(fault({ content: [heir], type: 'doc', version: 1 }), notANode) - const hidden: Record = { type: 'paragraph' } - Object.defineProperty(hidden, 'content', { value: [hidden] }) - assert.equal(fault({ content: [hidden], type: 'doc', version: 1 }), notANode) - const link: Record = 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 text = { marks: [bold], text: 'x', type: 'text' } const shared = { content: [text, text], type: 'paragraph' } diff --git a/src/adf/document.ts b/src/adf/document.ts index 290258b..6f45a23 100644 --- a/src/adf/document.ts +++ b/src/adf/document.ts @@ -106,7 +106,7 @@ export function isAdfNode(value: unknown): value is AdfNode { } 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 return !('attrs' in value) || isAttributes(value['attrs']) } @@ -135,7 +135,7 @@ function holdsItself(root: object): boolean { if (onPath.has(entry.item)) return true ancestors.push(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 } @@ -144,7 +144,7 @@ function isNodeArray(value: readonly unknown[]): value is readonly AdfNode[] { const pending: unknown[] = [...value] while (pending.length > 0) { 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 ('attrs' in node && !isAttributes(node['attrs'])) return false if ('marks' in node && !isArrayOf(node['marks'], isAdfMark)) return false @@ -219,11 +219,6 @@ function extraKey(value: Record, keys: readonly string[]): stri 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, keys: readonly string[]): boolean { - return keys.every((key) => !(key in value) || Object.prototype.propertyIsEnumerable.call(value, key)) -} - function holdsOnly(value: Record, keys: readonly string[]): boolean { return extraKey(value, keys) === undefined }