adf-codec/AGENTS.md

# Working in this repo

Decisions a reader would otherwise relitigate. Everything about *using* the library is in
`README.md`; what is still to build is in `todo.md`.

## 1. Three formats, ADF is the hub

ADF, one markdown flavour, one HTML dialect. Six directions are exposed, but markdown↔HTML compose
through ADF, so four conversions exist to keep correct — never write a fifth. A fourth format
(wiki markup, anything else) is refused: each one doubles the directions again.

## 2. The round-trip is the product

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

When losslessness and readability conflict, losslessness wins. A rare node may look ugly; nothing
is ever dropped for looks.

The other direction is a **canonical fixpoint**, not byte-identity: human markdown normalizes
(`*em*` and `_em_` become one ADF doc), converting back yields the library's canonical spelling,
and that spelling round-trips byte-identically. Byte-identity both ways would mean storing the
author's formatting choices in ADF, which has no place for them.

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

## 3. Unknown input policy

- **Unknown ADF node** (Atlassian ships undocumented types and adds more): carried opaquely — the
  raw JSON rides a dedicated syntax in markdown and HTML, and converts back byte-for-byte. The
  round-trip holds even for documents newer than the library.
- **Unmappable foreign HTML element**: error result naming the element. Arbitrary HTML can express
  what ADF cannot hold, so import maps a documented element set and refuses the rest — never a
  silent drop.
- **Bare `@name` / `:smile:` typed as plain text**: stays a text node. Only the directive syntax
  produces mention/emoji/media nodes — resolving names to ids needs I/O, which is the consumer's
  job (e.g. an autocomplete that inserts the directive).

## 4. The flavour

- **Directives**, one grammar for everything markdown lacks: `:::panel info` … `:::` for blocks,
  `:mention[@Mikael]{id=5b10a2}` style inline. Prior art: CommonMark's generic-directives proposal.
- **Plain CommonMark is a subset.** Anything a human types converts per the spec; the flavour only
  adds syntax, never changes CommonMark meaning.
- **Tables**: a simple table (one header row, plain inline cells — no spans, widths, colours, block
  content) emits a pipe table; anything richer emits the directive form.
- **Identity-bearing nodes** (`mention`, `media`, `emoji`) carry their ids in attributes. A
  converted document is therefore only portable within the site it came from — accepted.

The HTML dialect mirrors this: semantic elements, stable `adf-*` class names, `data-*` attributes
for what HTML cannot express, text content always escaped. No stylesheet ships — styling is the
consumer's.

## 5. Zero runtime dependencies

Nothing in `dependencies`, ever. TypeScript and whatever the tests need are `devDependencies`, and
they never reach a consumer. This means the CommonMark parser and the (well-formed) HTML parser are
written in this repo — a general parser would have to be extended into the flavour anyway.

## 6. The package contract

- **ESM only.** No CommonJS build, no dual-package hazard.
- **Two entrypoints.** Built JavaScript for ordinary consumers; TypeScript source for consumers
  running TypeScript directly through Node's type stripping.
- **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 — 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.

## 7. Nothing about any consumer

No Jira client, no HTTP, no REST response shapes, no issue keys — and no actual consumer named
anywhere in this repo. Design against the README's personas, not against a product. A consumer's
concern that leaks in here is a seam nobody declared.

## 8. Semver: the formats are API

The emitted markdown and HTML are contracts, not just the TypeScript surface. After 1.0: a change
that makes previously-emitted output parse differently, or stop parsing, is MAJOR; teaching the
parsers new syntax while old output still round-trips is MINOR. Documents in flight — stored,
cached, mid-edit — survive upgrades. Pre-1.0, normal 0.x rules apply.

## 9. Release automation

- `package.json` version on `main` is the source of truth. CI on every `main` push: tests green
  and version differs from npm's latest → publish and tag `vX.Y.Z`. A merge without a bump (docs,
  CI, dep bumps) deploys nothing; the bump in each shipping PR is a deliberate semver judgment.
- **Renovate** watches npm devDependencies, Docker image pins and action tags, and automerges
  every update — majors included — when CI is green.

## 10. 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 `docker run` against a
**full patch version** image tag (`node:24.19.0-alpine3.24`, never `node:24`).

The corpus, all checked in: hand-built fixtures per node and combination; real (sanitized) ADF
captured from live Atlassian APIs, including undocumented nodes; property-based generated ADF trees
(generator is a devDependency); the official CommonMark spec suite, run against `markdownToAdf`
(mapped) and `markdownToHtml`.

## 11. Style

Two-space indent, alphabetically sorted object keys, strict TypeScript. Failures are values:
every conversion returns `Result<T>` — `{ ok: true; value } | { ok: false; error: ConvertError }` —
and nothing throws. Input validation is structural only: what the walk needs (a node is an object
with a string `type`, known nodes have the attrs read from them), nothing more.

## 12. Non-goals

Stated so nobody builds them in: no wiki markup (§1), no network or filesystem I/O, no name→id
resolution (§3), no ADF schema validation or exported validator — whether Atlassian accepts a tree
is Atlassian's call — no shipped CSS (§4), no streaming APIs and no performance budget: conversions
are O(n) with no pathological blowups, and real documents are kilobytes. A CLI is a later goal
(`todo.md`), not a non-goal.