diff --git a/AGENTS.md b/AGENTS.md index 614fcc0..b0d3f6f 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 +- No value `JSON.parse` or `structuredClone` builds loops a call - 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 3123e48..5e1c5cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,8 @@ `collection`, `id` and `occurrenceKey` directly where they rode the opaque carry. - 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. ## 0.1.0 diff --git a/README.md b/README.md index e0e48f1..2b2c6d2 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 @@ -185,7 +185,7 @@ Emitting — `adfToMarkdown`, and `adfToHtml` at `0.2.0`: | Code | Fires when | What you can do | | --- | --- | --- | -| `not-an-adf-document` | the value handed in is no ADF document — a missing or wrong `type`, a stray key, a node that is not a node | guard the boundary you receive JSON at with `isAdfDocument`; the message names the branch that refused | +| `not-an-adf-document` | the value handed in is no ADF document — a missing or wrong `type`, a stray key, a node that is not a node, an object in the document holding itself | guard the boundary you receive JSON at with `isAdfDocument`; the message names the branch that refused | | `unsupported-document-version` | the document's `version` is not 1 | keep the ADF and pass the document over, or show it read-only; the version is the site's, not yours to change | Either direction. The emitter's own refusals are in this group — a parse reaches them by asking it @@ -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 call + loops forever on a string, or on a value `JSON.parse` or `structuredClone` builds. - 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 1f0c535..c5c18a2 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -384,10 +384,10 @@ input reads `message`. must invert before it reads as a failure — and where the flavour's claim refuses ordinary prose it names the escape that unclaims the form claimed: `\!adf:` for a directive, block line and inline alike, `\|` for every pipe row. -- `not-an-adf-document` carries the document's own path throughout: seven of the guard's eight - branches read the document's own shape, and threading a path to the eighth — a malformed node - anywhere in the tree — wants the manual stack §Nothing recurses unbounded forces. The message - names the violation instead. +- `not-an-adf-document` carries the document's own path throughout: seven of the guard's nine + branches read the document's own shape, and threading a path to the other two, which look anywhere + in the tree — a malformed node, or an object holding itself — wants the manual stack §Nothing + recurses unbounded forces. The message names the violation instead. ## Publish on a version bump @@ -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 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 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 20e3b37..5b66c8f 100644 --- a/src/adf/document.test.ts +++ b/src/adf/document.test.ts @@ -82,3 +82,23 @@ test("reads a node's siblings as a walk rather than as one call's arguments", () assert.equal(isAdfDocument(wide), true) assert.equal(fault(wide), 'accepted') }) + +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) + assert.equal(fault({ content: [paragraph], type: 'doc', version: 1 }), holdsItself) + const document: { content: unknown[]; type: string; version: number } = { content: [], type: 'doc', version: 1 } + document.content.push(document) + assert.equal(fault(document), holdsItself) + const attrs: Record = {} + attrs['a'] = [attrs] + 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 bold = { type: 'strong' } + const text = { marks: [bold], text: 'x', type: 'text' } + const shared = { content: [text, text], type: 'paragraph' } + const values = { b: 1 } + assert.equal(fault({ content: [shared, shared, { attrs: { a: [values, values] }, type: 'paragraph' }], type: 'doc', version: 1 }), 'accepted') +}) diff --git a/src/adf/document.ts b/src/adf/document.ts index 772dd34..6f45a23 100644 --- a/src/adf/document.ts +++ b/src/adf/document.ts @@ -43,6 +43,7 @@ export function adfDocumentFault(value: unknown): ConvertFault | undefined { const held: unknown = value['content'] if (!Array.isArray(held)) return notADocument(`an ADF document's content is an array: found ${describe(held)}`) const content: readonly unknown[] = held + if (holdsItself(content)) return notADocument('an ADF document is a tree: an object in it holds itself') if (!isNodeArray(content)) return notADocument("an ADF document's content holds ADF nodes: one of them is not") return nestingFault(content) } @@ -122,6 +123,23 @@ export function nodeMarks(node: { marks?: AdfMark[] }): readonly AdfMark[] { return node.marks ?? [] } +// Tracks ancestors alone: a tree may share an object, but an object holding itself walks the guards forever. +function holdsItself(root: object): boolean { + const pending = [{ depth: 0, item: root }] + const ancestors: object[] = [] + const onPath = new Set() + while (pending.length > 0) { + const entry = pending.pop() + if (entry === undefined) continue + while (ancestors.length > entry.depth) onPath.delete(ancestors.pop()) + if (onPath.has(entry.item)) return true + ancestors.push(entry.item) + onPath.add(entry.item) + for (const child of Object.values(entry.item)) if (typeof child === 'object' && child !== null) pending.push({ depth: entry.depth + 1, item: child }) + } + return false +} + function isNodeArray(value: readonly unknown[]): value is readonly AdfNode[] { const pending: unknown[] = [...value] while (pending.length > 0) { diff --git a/todo.md b/todo.md index 54b9978..5b1ebc7 100644 --- a/todo.md +++ b/todo.md @@ -6,7 +6,7 @@ `Bar = 9` -`Next ID = 66` +`Next ID = 67` | Goal | W | |---|---| @@ -24,12 +24,12 @@ | ID | Release | Exempt | Item | R | S | A | G | Goals | Score | |---|---|---|---|---|---|---|---|---|---| -| 63 | 0.2.0 | defect | **Refuse a cyclic input as `not-an-adf-document`.** | 2 | 2 | 6 | 9 | 1 | 27.5 | | 7 | 0.2.0 | | **Ship HTML: `adfToHtml`, `htmlToAdf`, and `markdownToHtml` / `htmlToMarkdown` composed through ADF.** | 6 | 9 | 9 | 9 | 2, 3 | 25.8 | | 55 | 0.2.0 | defect | **Spell every document the emitter refuses today for a carriage return, a NUL, a code-span line start, a newline inside an emoji, mention or status, or a text node whose text is empty or missing, or which holds content.** | 5 | 5 | 7 | 9 | 1 | 25.8 | | 45 | 0.2.0 | | **Replace `isAdfDocument` with a reader returning `Result`.** | 2 | 3 | 6 | 8 | 1 | 25.2 | | 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 | +| 66 | 0.2.0 | defect | **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 | | 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 | @@ -57,13 +57,6 @@ ## Details -### 63. Refuse a cyclic input as `not-an-adf-document`. - -`adfDocumentFault` walks with `isNodeArray` (`adf/document.ts`) and `isJsonValue` (`json-value.ts`), -worklists that record no visited object, so a node whose `content` holds itself hangs -`adfToMarkdown`, `adfToPlainMarkdown` and `isAdfDocument`; README §The guarantees promises no input -loops forever. - ### 7. Ship HTML: `adfToHtml`, `htmlToAdf`, and `markdownToHtml` / `htmlToMarkdown` composed through ADF. Lands after items 6, 59, 60, 61 and 62. The CommonMark spec suite also runs against @@ -109,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 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. Today `markdownToAdf` reads CommonMark and the lossless flavour as one input: text shaped like a