mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-19 06:35:44 +01:00
247 lines
20 KiB
Markdown
247 lines
20 KiB
Markdown
# todo
|
||
|
||
## Scoring
|
||
|
||
`Score = 100 * V / (2**S + 8)`
|
||
|
||
`Bar = 0.1`
|
||
|
||
`Next ID = 192`
|
||
|
||
## Items
|
||
|
||
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|
||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||
| 51 | 0.4.0 | | | **Match a reference label to its definition under Unicode case folding.** | 2 | 1 | 2 | 3 | 4 | 4 by 2 | 1.7 |
|
||
| 148 | 0.4.0 | | | **Ship conversion between ADF and Jira wiki markup both ways, under a README goal for wiki markup.** | 3 | 2 | 2 | 5 | 7 | 3 by 5 | 0.8 |
|
||
| 149 | 0.4.0 | | | **Read any HTML into ADF, in a call or option a developer panel picks, under a README goal for foreign HTML.** | 3 | 2 | 2 | 5 | 7 | 3 by 5 | 0.8 |
|
||
| 172 | 0.4.0 | | principle | **Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.** | 3 | 1 | 1 | 3 | 8 | code health by 2 | 0.6 |
|
||
| 107 | 0.4.0 | | decision | **Spell the block carry's JSON so its length stays linear in the node's JSON.** | 3 | 1 | 3 | 5 | 5 | | 0.0 |
|
||
| 170 | 0.4.0 | | owner | **Bundle the packed tarball with webpack, esbuild, Rollup and Bun in the gate, failing on any bundler warning, and run each bundle's round-trip in Node.** | 3 | 1 | 1 | 3 | 5 | | 0.0 |
|
||
| 42 | 0.5.0 | | defect | **Trim a text leaf's trailing blanks in linear time.** | 1 | 1 | 2 | 2 | 2 | 9 by 3 | 21.2 |
|
||
| 191 | 0.5.0 | | defect | **Make the edge trim and the reference of its property test agree on a line whose strong link run ends in blanks before two hard breaks.** | 2 | 1 | 2 | 3 | 2 | code health by 3 | 21.2 |
|
||
| 31 | 0.5.0 | | | **Make the branch-coverage figure repeat across runs of an unchanged tree.** | 2 | 1 | 1 | 2 | 3 | code health by 3 | 15.9 |
|
||
| 57 | 0.5.0 | | | **Make each `ci.sh` leg build what it reads, so one leg run alone tests the current tree.** | 2 | 1 | 1 | 2 | 3 | code health by 3 | 15.9 |
|
||
| 38 | 0.5.0 | | defect | **Spell a lone surrogate in a text node so it survives a UTF-8 encode.** | 1 | 1 | 2 | 2 | 2 | 1 by 2 | 14.2 |
|
||
| 76 | 0.5.0 | | | **State the files the package does not ship once, so the build, the lint ceiling, the coverage exclusions and the mutation run cannot drift apart.** | 1 | 1 | 1 | 1 | 2 | code health by 2 | 14.2 |
|
||
| 56 | 0.5.0 | | | **Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.** | 3 | 1 | 2 | 4 | 5 | code health by 5 | 10.6 |
|
||
| 118 | 0.5.0 | | | **Spell a portable link's title through `oneLine`.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 8.5 |
|
||
| 183 | 0.5.0 | | | **Answer developer-community topic 41858 once 0.4.0 is published.** | 1 | 1 | 1 | 1 | 1 | 3 by 2, 6.2 by 2 | 7.9 |
|
||
| 82 | 0.5.0 | | | **Give the directive tests and fixtures random UUID v7 ids in place of `a-1`, `a`, `x` and `h`.** | 2 | 1 | 1 | 2 | 3 | code health by 1 | 5.3 |
|
||
| 178 | 0.5.0 | | owner | **Reach the comprehension floor: move the reasoning behind the emitter's fallback and escape loops into the code that runs them, so each reads on its own.** | 3 | 1 | 2 | 4 | 7 | code health by 8 | 5.0 |
|
||
| 58 | 0.5.0 | | | **Port `ci.sh`, `publish.sh`, `docker-runner.sh` and `mutation-tests/run.sh` to standalone Python scripts.** | 4 | 2 | 2 | 6 | 6 | code health by 3 | 3.5 |
|
||
| 187 | 0.5.0 | | | **Write a `blockTaskItem` and a nested task list as HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 3 | 6 by 2 | 2.4 |
|
||
| 9 | 0.5.0 | | | **Ship an online sandbox: a web page with two textboxes converting between ADF and markdown on the library's browser build.** | 3 | 2 | 1 | 4 | 6 | 3 by 6 | 1.7 |
|
||
| 34 | 0.5.0 | | | **Read emphasis flanking by the whole character beside an astral symbol.** | 2 | 1 | 2 | 3 | 3 | 4 by 1 | 1.2 |
|
||
| 74 | 0.5.0 | | owner | **Keep the release path publishing after npm retires bypass-2FA tokens.** | 3 | 2 | 4 | 7 | 4 | | 0.0 |
|
||
| 8 | 0.6.0 | | owner | **Ship a CLI.** | 3 | 2 | 1 | 4 | 7 | | 0.0 |
|
||
| 139 | 0.7.0 | | decision | **Ship the calls between markdown and HTML, composed through ADF and each named by its flavour.** | 2 | 1 | 2 | 3 | 4 | 3 by 3 | 2.6 |
|
||
| 137 | 0.7.0 | | decision | **Read foreign HTML in `htmlToAdf` the three ways `docs/decisions.md` §Foreign HTML sorts three ways states.** | 2 | 1 | 2 | 3 | 4 | 4 by 2 | 1.7 |
|
||
| 138 | 0.7.0 | 137 | | **Read raw HTML in every markdown reader through `htmlToAdf`'s foreign-element mapping, in place of refusing it as `unmappable-html`.** | 3 | 1 | 3 | 5 | 5 | 4 by 4 | 2.0 |
|
||
|
||
## Renamed
|
||
|
||
- 0.2.1 renamed to 0.3.0
|
||
|
||
## Details
|
||
|
||
### 51. Match a reference label to its definition under Unicode case folding.
|
||
|
||
`link-syntax.ts` normalizes a label with `toLowerCase`, so `[ẞ]` misses its `[SS]` definition (spec
|
||
example 540). Fold with Unicode's full case folding, `CaseFolding.txt`'s C and F mappings, shipped
|
||
as data per §Standards ship as data: lowercasing and then uppercasing would also merge `ı` with
|
||
`I`, which folding keeps apart, so add that pair as a fixture. Breaking: `MIGRATION.md`'s Readings table
|
||
gains its row. Its `pending` exceptions go, and the README's guarantees drop the case-folding
|
||
exception and count one fewer.
|
||
|
||
### 148. Ship conversion between ADF and Jira wiki markup both ways, under a README goal for wiki markup.
|
||
|
||
Jira's REST API v2 and its changelogs carry wiki markup, and Atlassian's
|
||
`WikiMarkupTransformer` is the only converter; community threads report its round-trip losing
|
||
expands, layouts and some marks. Add the goal to the README's `## Goals` in the same change. Split
|
||
into items before starting. The maintainer, 2026-10-28: ship what exists first, so this waits for
|
||
0.4.0.
|
||
|
||
### 149. Read any HTML into ADF, in a call or option a developer panel picks, under a README goal for foreign HTML.
|
||
|
||
`htmlToAdf` reads only what `adfToHtml` writes. The most asked need on the Atlassian
|
||
developer community is HTML from emails, CMSs and editors into ADF. The maintainer, 2026-10-28:
|
||
reading foreign HTML is a separate goal, added to the README in this change. Before building, a
|
||
panel of the developer personas picks the API among those the goals allow: a parameter on
|
||
`htmlToAdf` or a separate call; Goal 8's "nothing to configure" and Goal 6.1's naming bear on the
|
||
choice. Split into items once the API is picked.
|
||
|
||
### 172. Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.
|
||
|
||
134 loops run several readers or cases inside one test body, for example
|
||
`for (const read of [commonMarkToAdf, losslessMarkdownToAdf, portableMarkdownToAdf])` at lines 97,
|
||
279, 771, 917, 926, 962 and 1118 of `src/markdown/parse/markdown-to-adf.test.ts`; the most are in
|
||
`adf-schema.test.ts` (18), `limits.test.ts` (12) and `portable-markdown-to-adf.test.ts` (10). The
|
||
first failing reader stops the test and the failure never names the reader. Write
|
||
``for (const read of readers) test(`… in ${read.name}`, …)`` at the top level. Technical principle:
|
||
"No loops or branches in a test body; parametrize the cases". Found by the principles audit of the
|
||
release review of 0.3.0, 2026-11-08.
|
||
|
||
### 107. Spell the block carry's JSON so its length stays linear in the node's JSON.
|
||
|
||
The block carry indents two spaces a level, so about 1 MB of deeply nested arrays in a carried
|
||
node's JSON spells past V8's longest string, which the writers refuse as `unsupported-node-shape`;
|
||
the inline carry's compact JSON would fit. docs/decisions.md §The code list calls a refusal no
|
||
spelling recovers from a gap in the flavour. Respelling the carry changes the format (§The formats
|
||
are API). Found by the README-goals audit of item 83, 2026-10-11.
|
||
|
||
### 170. Bundle the packed tarball with webpack, esbuild, Rollup and Bun in the gate, failing on any bundler warning, and run each bundle's round-trip in Node.
|
||
|
||
Consumers bundle the package, Forge apps with webpack among them, and one reported a "Critical
|
||
dependency" warning from another converter. Nothing in the gate bundles it today. Install the
|
||
tarball as `package-tests` does, bundle an entry file that round-trips one document through
|
||
`adfToLosslessMarkdown` and `losslessMarkdownToAdf`, and run each bundle in Node. A warning fails the
|
||
leg as an error does: webpack's "Critical dependency" is a warning. The bundlers live in
|
||
`bundle-size/`'s package, beside esbuild, as Stryker lives in its own (§Stryker in its own package), with
|
||
pinned versions. Bun builds from the
|
||
image the gate already pulls. No leg needs an account or a network beyond the install.
|
||
|
||
Once the leg holds, the README may say the package bundles with those four; it says nothing about
|
||
Forge's runtime, which no leg tests.
|
||
|
||
### 42. Trim a text leaf's trailing blanks in linear time.
|
||
|
||
`portable/inline-reduction.ts`'s `leafEdges` finds the trail with an unanchored `/[ \t]*$/`,
|
||
quadratic in a run of blanks inside one leaf: a paragraph of `a`, 80 000 spaces, `b` takes 6.5 s in
|
||
`adfToPortableMarkdown`. Scan backward, as the expand title's trim does. `edgeWhitespace`, in the
|
||
same file, counts a leaf's lead and trail by index.
|
||
|
||
### 191. Make the edge trim and the reference of its property test agree on a line whose strong link run ends in blanks before two hard breaks.
|
||
|
||
Found while shipping item 190, on `origin/main`'s trim as well as on that chunk's: fast-check seed 578490788, path `94554:1:8:16:15:15:16:16:16:16`, in `trims a spanned line as the reference counts trim it, in no more passes` (`src/markdown/portable/inline-reduction.test.ts`), about one random line in 100 000, so the gate's 3 000 runs on a fixed seed pass. The line, with `held` a link to `v` and `strong`: `'x '` holding `held` and `backgroundColor`, `' '` holding `held`, `' '` unmarked, a hard break, `' '` holding `held`, `' '` unmarked, a hard break. `trimmedEdges` returns the one leaf `'x'`; the reference, `trimPass` on `runsSharedWithNext`'s counts, also keeps a linked `' '`. Decide which is right by `docs/decisions.md` → "After 32 passes…" and the trim's entries, then fix the other and pin the line as a fixed test. A second line of the class, with no link and one hard break: seed -1783810909, path `201490:2:4:5:9:9:9:15:14:18:18:18:18:22:23:23`, the line `'x '` strong, `' '` code, `' '` strong, a hard break, `' '` unmarked, `'x '` strong, `' '` unmarked; the trim gives `x`, `' '`, `' '`, hard break, `x`, the reference `'x '`, `' '`, hard break, `x`.
|
||
|
||
### 31. Make the branch-coverage figure repeat across runs of an unchanged tree.
|
||
|
||
Three Node test legs over one unchanged tree reported `emit/inline-line.ts` at 95.83%, 96.23% and
|
||
96.23%, and the total at 98.80%, 98.84% and 98.84% (2026-09-21). `--experimental-test-coverage`
|
||
counts branches off V8's own coverage, which the runner's parallel files and V8's optimization make
|
||
run-dependent, so the number the floor is read against is not the code's alone. The floor of 98
|
||
holds today on 0.8 points of slack and `docs/decisions.md` §The coverage floors says it only ever
|
||
moves upward, so the first raise to the measured figure reddens a run that changed nothing. Make the
|
||
measurement repeatable, or state the number the floor may be raised to and why it is not the
|
||
measured one.
|
||
|
||
### 57. Make each `ci.sh` leg build what it reads, so one leg run alone tests the current tree.
|
||
|
||
Technical principle "Compose, do not entangle": Deno, Bun and the tests read the install leg's
|
||
`node_modules`, the floor and consumer legs the pack leg's, and the browser leg whatever `dist/` the
|
||
build leg left, so a leg run alone can pass on stale output.
|
||
|
||
### 38. Spell a lone surrogate in a text node so it survives a UTF-8 encode.
|
||
|
||
`adfToLosslessMarkdown` emits it verbatim, so markdown stored as UTF-8 reads back U+FFFD; attribute
|
||
values already escape it.
|
||
|
||
### 76. State the files the package does not ship once, so the build, the lint ceiling, the coverage exclusions and the mutation run cannot drift apart.
|
||
|
||
Technical principle DRY: the set is written in `tsconfig.build.json`'s `exclude`, `.oxlintrc.json`'s
|
||
`ignorePatterns` and the `test` script's two `--test-coverage-exclude` flags, and §The size ratchet
|
||
assumes they agree. A helper added to one list lints test code under the shipped ceiling, or drops
|
||
shipped code from coverage, silently. Derive the others from one, or assert in a test that
|
||
they agree. Found by the technical-principles audit, 2026-10-04.
|
||
|
||
`mutation-tests/run.sh`'s pathspec restates the test files and test helpers, and
|
||
`mutation-tests/stryker.config.mjs`'s `testFiles` the test files, so a helper missing from the
|
||
pathspec has its mutants read as survivors. Found by the architecture review of item 152, 2026-10-28.
|
||
|
||
### 56. Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.
|
||
|
||
Technical principle "One owner per value": the `Walk` record passes through functions that mutate it
|
||
and return `void`; `walk.leaf` alone is written in seven places, and `openedList` reads the
|
||
`endedLists` that `closeLeaf` fills. `ContainerStack` in the same file shows the shape to follow. `inline-content.ts`'s `Scan` has the same shape: about fifteen
|
||
functions write `pending`, `pieces`, `brackets`, `linkOpenersFrom` and `openingSpellableLink` on the `Scan`
|
||
they are handed, most of them returning `void`, and `parseInlineContent` reads a flag `scanInline` leaves on it. The same shape recurs in
|
||
`mintTaskIds` (`portable/task-ids.ts`), which writes `attrs` on the document `readDocument` built;
|
||
`takeFallback` (`emit/inline-line.ts`), which writes the record the next `lineSegments` pass reads;
|
||
`writeUnpaired` and `markHighlights` (`inline-content.ts`), whose order changes the
|
||
output.
|
||
Once `Scan`'s pieces have owners, the bracket resolution — `linkedAlt` through `linkTo`,
|
||
`holdsLink`, and `closeBracket` through `altText` — can leave `inline-content.ts` (about 690 lines)
|
||
for a module of its own. That module resolves an image once, into a node holding its alt text and
|
||
its link, so `imageAlt`, `resolvedPieces` and `directiveMarkPieces` no longer filter and regroup
|
||
`ImageLink` pieces. Found by the architecture pass of the release review of 0.3.0, 2026-11-08.
|
||
|
||
### 118. Spell a portable link's title through `oneLine`.
|
||
|
||
`portableLink` (`src/markdown/portable/inline-reduction.ts`) repeats `oneLine`'s replacements by
|
||
hand, so a change to what a portable line drops would miss link titles. Technical principle: DRY.
|
||
Found by the principles audit of item 99, 2026-10-14.
|
||
|
||
### 183. Answer developer-community topic 41858 once 0.4.0 is published.
|
||
|
||
Topic 41858 asks for ADF as plain text. `adfToPlainText` now writes tables, images, cards, extensions and expand titles, so the answer names what it writes. Post it only after 0.4.0 publishes (§Posts announcing a release wait for its publish). The post is the maintainer's (the maintainer, 2026-10-28). It sits in 0.5.0 because the post can only go out after 0.4.0 publishes, so no chunk of 0.4.0 can finish it.
|
||
|
||
### 82. Give the directive tests and fixtures random UUID v7 ids in place of `a-1`, `a`, `x` and `h`.
|
||
|
||
Technical principle: tests use random UUID v7 ids; `portable-markdown-to-adf.test.ts` already does.
|
||
Found by the technical-principles audit of item 78, 2026-10-05.
|
||
|
||
### 178. Reach the comprehension floor: move the reasoning behind the emitter's fallback and escape loops into the code that runs them, so each reads on its own.
|
||
|
||
The scoring run at fa8600f (PR #162) averaged 5.88 overall, under the 7.0 floor; Locality and Self-sufficiency scored lowest, at 5.38 each. Make these places, the ones every seat named, easier to read:
|
||
|
||
- `src/markdown/emit/unspellable-runs.ts:223` `pairStanding` / `pairVerdicts`: the case analysis behind the two sweeps lives only in `docs/decisions.md`. State it in the types or the code, with one vocabulary.
|
||
- `src/markdown/emit/inline-line.ts:120` `settledLine`: fallbacks change the `carried` Set and `openingLinkAsDirective` out of sight. Make each pass's state an explicit value, with the 32-pass bound visible where it holds.
|
||
- `src/markdown/emit/line-escaping.ts:99` `readBack`: say in the code why three escape passes suffice.
|
||
- `src/markdown/inline-content.ts:255` and `:424` (`directiveMarkPieces`, `closeBracket`, `applyClosing`): one mutable `Scan` shared by nine piece kinds in a 695-line file. Split it by piece kind.
|
||
- `src/markdown/emit/adf-to-markdown.ts:138` `spellingMemo`: keep its take, ask and depth rebasing in one type.
|
||
|
||
Keep every output byte-identical: the round-trip properties and the CommonMark suite must pass unchanged.
|
||
|
||
### 58. Port `ci.sh`, `publish.sh`, `docker-runner.sh` and `mutation-tests/run.sh` to standalone Python scripts.
|
||
|
||
Technical principle "Prefer a standalone Python script over a shell script": `AGENTS.md` §3 teaches
|
||
bash footguns (`&&` chaining under `||`, `tee /dev/stderr`) the port removes. A wrong line range in
|
||
`run.sh` mutates the wrong lines without failing, so the port tests how it reads diff hunks.
|
||
|
||
### 187. Write a `blockTaskItem` and a nested task list as HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.
|
||
|
||
The reader panel of §The HTML dialect expected a `blockTaskItem` as an `<li>` of two `<p>` and a nested task list as an inner `<ul>`. The writer panel's spellings left both on the carry, since a task item holds inline content alone. A writer panel settles the two spellings (AGENTS.md §7); the item takes it and writes the HTML both ways.
|
||
|
||
### 34. Read emphasis flanking by the whole character beside an astral symbol.
|
||
|
||
Check whether `delimiterRunToken` (`inline-tokens.ts`) and `resolveEmphasis` (`line-escaping.ts`)
|
||
read one UTF-16 unit beside an astral symbol. A lone surrogate is neither punctuation nor symbol,
|
||
but CommonMark reads `😀` as punctuation. Where they do, read the code point, with a fixture per
|
||
direction.
|
||
|
||
### 74. Keep the release path publishing after npm retires bypass-2FA tokens.
|
||
|
||
Lands after 2027-01-01, or after a release run fails on the token, whichever comes first: the
|
||
maintainer chose on 2026-10-02 to wait and see whether the retirement bites. It holds back no
|
||
release: when the rest of its release is done, it moves to the next. `0.1.0` published only once the
|
||
npm token carried **Bypass 2FA**: the account requiring no 2FA on writes was not enough, and npm
|
||
answered `EOTP` until the token itself bypassed. npm retires bypass-2FA tokens for direct publishing
|
||
around January 2027, leaving them `npm stage publish`, which a maintainer approves with 2FA. Trusted
|
||
publishing over OIDC replaces the token, and GitHub-hosted Actions support it. The release has run
|
||
there since 2026-10-04, still with the organization's `NPM_TOKEN`: the maintainer chose to keep the
|
||
token for now. The trade is the maintainer's: move `publish.sh` to trusted publishing, or to the
|
||
staged publish, which fits badly with publish-on-merge. Its Moves cell is empty: no README goal covers
|
||
the release path.
|
||
|
||
### 8. Ship a CLI.
|
||
|
||
Its Moves cell is empty: no README goal or persona covers a CLI yet. The chunk
|
||
proposes both (the maintainer, 2026-10-02), and they land in the README's `## Goals` and `##
|
||
Audience` with the CLI.
|
||
|
||
### 139. Ship the calls between markdown and HTML, composed through ADF and each named by its flavour.
|
||
|
||
Waits until a consumer needs it. Which flavours get a composed call is this item's to settle; the
|
||
CommonMark spec suite runs against the one reading CommonMark, checked against the spec's expected
|
||
HTML. Where a composed call naming a markdown `Flavour` sits is this item's to settle.
|
||
|
||
### 137. Read foreign HTML in `htmlToAdf` the three ways `docs/decisions.md` §Foreign HTML sorts three ways states.
|
||
|
||
Waits until a consumer needs `htmlToAdf` to read HTML that `adfToHtml` did not write.
|
||
|
||
### 138. Read raw HTML in every markdown reader through `htmlToAdf`'s foreign-element mapping, in place of refusing it as `unmappable-html`.
|
||
|
||
Waits until a consumer needs it. The change touches `inline-content.ts` and `markdown-to-adf.ts`,
|
||
places the comprehension seats found hard; leave each place it touches easier to read.
|