adf-codec/AGENTS.md

Working in this repo

Decisions that a reader would otherwise relitigate. Everything about using the library is in README.md; what is still to build, and what is still undecided, is in todo.md.

1. Two formats, never three

ADF and one markdown flavour. No HTML — not as an output, not as an intermediate, not as a convenience export. A consumer that wants HTML renders the markdown itself, with its own escaping and its own stylesheet; a consumer that wants neither shows the markdown verbatim, which is what the first one does.

Three formats would mean six directions to keep lossless instead of two.

2. The round-trip is the product

markdownToAdf(adfToMarkdown(doc)) must equal doc. Anything less and a consumer that lets someone edit a ticket destroys what it could not represent — a panel, a mention, an attachment — in a document it did not author.

That is why the flavour is extended: markdown has no syntax for most of what ADF holds, so the flavour invents it. Designing that syntax is the first real task, and it is open (todo.md).

Two consequences to settle before any node is implemented, not after:

• What happens to a node the library does not know. The documented ADF node set is not the whole schema, and Atlassian adds to it. Whether an unknown node is carried opaquely, refused, or dropped is a correctness decision for the whole library, and it decides the return shape of both functions.
• Whether a lossless document must stay readable to a plain markdown reader. Anything the flavour invents is noise to a reader that does not know it. How much noise is acceptable bounds the syntax.

Round-trip equality is a property to test over a corpus, not a claim to make in prose.

3. Zero runtime dependencies

Nothing in dependencies, ever. TypeScript and whatever the tests need are devDependencies, and they never reach a consumer. A markdown parser is exactly the dependency this rule exists to refuse: the flavour is not CommonMark, so a general parser would have to be extended into one anyway.

4. The package contract

• ESM only. No CommonJS build, no dual-package hazard.
• Two entrypoints. The built JavaScript for ordinary consumers, and the TypeScript source for consumers that run TypeScript directly through Node's type stripping — the first consumer is one, which is why this exists.
• Types for both. The JavaScript entrypoint ships .d.ts beside it; the TypeScript entrypoint is its own types.
• Published to public npmjs as @larvit/atlassian-adf-converter, matching @larvit/log. Public means the source is public: the Gitea repo starts private, and going public — with the LICENSE in place — is a step before the first publish, not after it.
• Exact versions. save-exact=true in .npmrc, as in every other repo here.

5. Nothing about any consumer

No Jira, no HTTP, no REST response shapes, no plainpages, no issue keys. The library takes a document tree and returns a string, or the reverse. A consumer's concern that leaks in here is a seam nobody declared — and the reason this is a library at all rather than a file in the client that needed it.

6. Tests first, in Docker

Write the test for the behaviour wanted, then implement until it passes. node --test, beside the code. Node, tsc and npm never run on the host — a compose service or a docker run against a full patch version image tag (node:24.19.0-alpine3.24, never node:24), so the same commit builds the same thing on a different day.

7. Style

Two-space indent, alphabetically sorted object keys, strict TypeScript. Failures are values, not exceptions: a function that both returns a result and throws for some inputs has two error channels.