320 lines
22 KiB
Markdown
320 lines
22 KiB
Markdown
# todo
|
|
|
|
## Scoring
|
|
|
|
`Score = -R - S/4 + 2*A + 2*G*W`
|
|
|
|
`Bar = 9`
|
|
|
|
`Next ID = 74`
|
|
|
|
| Goal | W |
|
|
|---|---|
|
|
| 1 | 1.00 |
|
|
| 2 | 0.89 |
|
|
| 3 | 0.78 |
|
|
| 4 | 0.67 |
|
|
| 5 | 0.56 |
|
|
| 6 | 0.44 |
|
|
| 7 | 0.33 |
|
|
| 8 | 0.22 |
|
|
| 9 | 0.11 |
|
|
|
|
## Items
|
|
|
|
| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |
|
|
|---|---|---|---|---|---|---|---|---|---|
|
|
| 7 | 0.2.0 | | **Ship HTML: `adfToHtml`, `htmlToAdf`, and `markdownToHtml` / `htmlToMarkdown` composed through ADF.** | 6 | 9 | 9 | 9 | 2, 4 | 25.8 |
|
|
| 45 | 0.2.0 | | **Replace `isAdfDocument` with a reader returning `Result<AdfDocument>`.** | 2 | 3 | 6 | 8 | 1 | 25.2 |
|
|
| 67 | 0.2.0 | defect | **Push an expand title's leaves one at a time, so a title carrying many text nodes returns a result.** | 1 | 1 | 4 | 9 | 1 | 24.8 |
|
|
| 6 | 0.2.0 | decision | **Specify the HTML dialect.** | 2 | 6 | 7 | 8 | 2, 4 | 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, 8 | 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 |
|
|
| 71 | 0.2.0 | | **Compare the package with the other ADF converters in the README, each claim checked against that package's own docs or behaviour.** | 1 | 3 | 6 | 7 | 3 | 21.2 |
|
|
| 43 | 0.2.0 | decision | **Give each markdown input its own reader, strict to its own standard.** | 6 | 7 | 8 | 9 | 4, 5 | 20.3 |
|
|
| 68 | 0.2.0 | | **Carry a non-text inline node holding `content` or `text`, a block holding `text`, and a leaf block holding `content`.** | 3 | 3 | 4 | 7 | 1 | 18.2 |
|
|
| 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 | 4, 5, 7 | 17.1 |
|
|
| 70 | 0.2.0 | | **Give `package.json` the `keywords` someone searching npm for an ADF converter types.** | 1 | 1 | 4 | 6 | 3 | 16.1 |
|
|
| 72 | 0.2.0 | | **Make GitHub the canonical repository, with `gitea.larvit.se/larvit/adf-codec` a read-only pull mirror of it.** | 5 | 6 | 5 | 8 | 3 | 16.0 |
|
|
| 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 | 4, 5 | 15.5 |
|
|
| 61 | 0.2.0 | decision | **Have the emitter ask the inline reader how a line reads back, in place of `line-escaping.ts` predicting it.** | 6 | 8 | 3 | 8 | 1 | 14.0 |
|
|
| 52 | 0.2.0 | | **Spell `colwidth` as a comma list, `colwidth="340,420"`.** | 3 | 3 | 5 | 6 | 6 | 11.5 |
|
|
| 51 | 0.2.0 | | **Match a reference label to its definition under Unicode case folding.** | 2 | 2 | 2 | 7 | 4, 5 | 10.9 |
|
|
| 60 | 0.2.0 | decision | **Collect the questions `parse/` asks `emit/` into one named module.** | 3 | 4 | 2 | 6 | 2 | 10.7 |
|
|
| 59 | 0.2.0 | decision | **Group the directive grammar into `src/markdown/directive/`, move `Read<T>` to `result.ts`, and move `Flavour` to `markdown/flavour.ts`.** | 3 | 5 | 2 | 6 | 2 | 10.4 |
|
|
| 53 | 0.2.0 | | **Put a block's `marks` spelling to the writer panel and adopt its pick.** | 4 | 5 | 5 | 6 | 6 | 10.0 |
|
|
| 62 | 0.2.0 | decision | **Move the plain flavour's reading out of `parse/` and its writing out of `emit/` into `markdown/plain/`, so `emit/` no longer imports `plain/`.** | 4 | 5 | 2 | 6 | 2 | 9.4 |
|
|
| 50 | 0.2.0 | | **Read `[](/url)` and `[]()` as CommonMark's empty link.** | 4 | 4 | 3 | 6 | 4, 5, 7 | 9.0 |
|
|
| 47 | 0.3.0 | | **Open the README with what the package is, what it does and for whom.** | 1 | 4 | 7 | 9 | 3 | 26.0 |
|
|
| 73 | 0.3.0 | | **Announce the package where someone needing an ADF converter already reads: JRACLOUD-77436, the Atlassian developer community and Stack Overflow's ADF-to-markdown questions.** | 1 | 2 | 6 | 8 | 3 | 23.0 |
|
|
| 9 | 0.3.0 | | **Ship an online sandbox: a web page with two textboxes converting between ADF and markdown on the library's browser build.** | 2 | 6 | 6 | 8 | 3 | 21.0 |
|
|
| 38 | 0.3.0 | | **Spell a lone surrogate in a text node so it survives a UTF-8 encode.** | 2 | 2 | 4 | 7 | 1 | 19.5 |
|
|
| 48 | 0.3.0 | | **Keep the release path publishing past npm's bypass-2FA token retirement.** | 4 | 4 | 8 | 3 | 3 | 15.7 |
|
|
| 46 | 0.3.0 | | **Publish the bundle size in the README, failing the release pipeline when it drifts.** | 2 | 4 | 5 | 5 | 3, 8 | 14.8 |
|
|
| 34 | 0.3.0 | | **Read emphasis flanking by the whole character beside an astral symbol.** | 2 | 3 | 3 | 6 | 4, 5 | 11.3 |
|
|
| 31 | 0.3.0 | | **Make the branch-coverage figure repeat across runs of an unchanged tree.** | 2 | 3 | 3 | 4 | 1 | 11.2 |
|
|
| 42 | 0.3.0 | | **Trim a text leaf's trailing blanks in linear time.** | 1 | 2 | 5 | 9 | 9 | 10.5 |
|
|
| 56 | 0.3.0 | principle | **Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.** | 4 | 5 | 2 | 4 | 1 | 6.8 |
|
|
| 57 | 0.3.0 | principle | **Make each `ci.sh` leg build what it reads, so one leg run alone tests the current tree.** | 2 | 3 | 1 | 3 | 8 | 0.6 |
|
|
| 58 | 0.3.0 | principle | **Port `ci.sh`, `publish.sh` and `docker-runner.sh` to standalone Python scripts.** | 4 | 6 | 1 | 2 | 8 | -2.6 |
|
|
| 8 | 0.4.0 | | **Ship a CLI.** | 3 | 7 | 7 | 6 | 3 | 18.6 |
|
|
|
|
## Details
|
|
|
|
### 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
|
|
`markdownToHtml`. The README documents HTML as it documents markdown.
|
|
|
|
### 45. Replace `isAdfDocument` with a reader returning `Result<AdfDocument>`.
|
|
|
|
Goal 1 has every call return a result; the boolean guard is the one export that does not, and it
|
|
cannot say which branch refused, where `not-an-adf-document`'s message already does. Breaking:
|
|
`MIGRATION.md` shows the guard's replacement.
|
|
|
|
### 67. Push an expand title's leaves one at a time, so a title carrying many text nodes returns a result.
|
|
|
|
`quoteNode`'s title loop (`parse/markdown-to-adf.ts`) spreads `inlineLeaves`'s result into
|
|
`push`, against `docs/decisions.md` §Nothing spreads an unbounded array: an inline carry in a
|
|
folded callout's title holding an unknown node with ~125k text children throws a `RangeError` from
|
|
`plainMarkdownToAdf`. Found by the README-goals audit, 2026-10-04.
|
|
|
|
### 6. Specify the HTML dialect.
|
|
|
|
Element-by-element mapping, the `data-*` fidelity scheme, the opaque-carry form, and the documented
|
|
foreign-element set `htmlToAdf` accepts — the set `markdownToAdf` shares (`spec/flavour.md` §Raw
|
|
HTML in input). The set sorts per `docs/decisions.md` §Foreign HTML sorts three ways.
|
|
|
|
### 64. Read back unchanged on V8 every JSON key the emitter writes, with a fixture whose key holds `\`, `"` or a control character.
|
|
|
|
`property-harness.ts` strips `\`, `"` and control characters from generated JSON keys, citing V8's
|
|
`JSON.parse` returning a wrong key for an escaped backslash. The library reads `json` attributes
|
|
(`directive-syntax.ts`) and both carries (`opaque-carry.ts`) through that `JSON.parse`, so on Node,
|
|
Deno and Chrome the round-trip would refuse its own output or read back a different key; the fixture
|
|
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.
|
|
|
|
### 71. Compare the package with the other ADF converters in the README, each claim checked against that package's own docs or behaviour.
|
|
|
|
Lands after item 7, whose HTML the comparison names. A table: which directions each converts,
|
|
whether the round-trip holds, what an unknown node does, the formats, runtime dependencies and
|
|
size. Candidates are the packages an npm search for ADF and markdown returns, marklassian among
|
|
them. Every cell cites that package's README or a run against its published version, since a
|
|
reader relies on it. Found while planning discoverability, 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
|
|
directive, a pipe table or a `~~` pair becomes a flavour node where CommonMark reads plain text, and
|
|
a code fence whose info string opens `adf:` becomes the block carry where CommonMark reads code. A
|
|
caller names the markdown it hands in: CommonMark, read as its spec says, or the lossless flavour,
|
|
read as `spec/flavour.md` says. Breaking: `MIGRATION.md` says which call a caller takes.
|
|
|
|
### 68. Carry a non-text inline node holding `content` or `text`, a block holding `text`, and a leaf block holding `content`.
|
|
|
|
`refuseContentAndText` (`emit/inline-line.ts`) and `emitDirectiveBlock` (`emit/adf-to-markdown.ts`)
|
|
refuse these with `unsupported-node-shape`, though `isAdfDocument` accepts them and the carry
|
|
round-trips them; `docs/decisions.md` §The code list gives a cause the carry answers no code. Drop
|
|
them from the emitting half of the README's `unsupported-node-shape` row. Found by the README-goals
|
|
audit, 2026-10-04.
|
|
|
|
### 65. 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.
|
|
|
|
Both are refused today with `unmappable-image`: 14 examples in
|
|
`corpus/commonmark-spec/refusals.json`, a bot's `See  here` among them. `mediaInline`
|
|
takes only Atlassian media ids, never a URL. An image not alone in its paragraph reads as its alt
|
|
text, linked to its URL. Its title becomes the link's `title`. An empty alt text reads as the URL,
|
|
as item 50 reads an empty link. A titled image alone in its paragraph reads as the image, with its
|
|
title as a `caption` (the maintainer, 2026-10-04). By Goal 5, the lossless flavour reads both as
|
|
CommonMark does. An image inside a link: `[](/uri)` (spec example 517). Alone in
|
|
its paragraph, it reads as the image with a `link` mark to `/uri`, which ADF's `media` takes. Not
|
|
alone in its paragraph, the image reads as its alt text linked to `/uri`, and its URL drops. A
|
|
writer panel chose this reading 3 of 3 (2026-10-04), by Goal 6, which outranks Goal 7.
|
|
|
|
### 70. Give `package.json` the `keywords` someone searching npm for an ADF converter types.
|
|
|
|
`package.json` has none, and npm's search ranks on them. Take the terms the other ADF converters on
|
|
npm list and the names the README uses — ADF, Atlassian Document Format, markdown, CommonMark, HTML
|
|
— so a search for any of them can reach the package. Found while planning discoverability,
|
|
2026-10-04.
|
|
|
|
### 72. Make GitHub the canonical repository, with `gitea.larvit.se/larvit/adf-codec` a read-only pull mirror of it.
|
|
|
|
The maintainer's call, 2026-10-04: GitHub is where an ADF converter is searched for, and the Gitea
|
|
copy keeps the move back open. The workflows move to `.github/workflows/` with `ci.sh` and
|
|
`publish.sh` unchanged; `package.json`'s `repository`, `bugs` and `homepage`, the README's,
|
|
CHANGELOG's and MIGRATION's links, and AGENTS.md's forge commands and merge style follow.
|
|
`docs/decisions.md` gains the entry "GitHub is canonical, and Gitea a pull mirror of it" (Goal 3),
|
|
and every entry naming Gitea Actions is revised. Creating the GitHub repository, its `NPM_TOKEN`
|
|
secret, and re-creating the Gitea copy as a mirror — Gitea converts a repository to a mirror only
|
|
that way — are the maintainer's.
|
|
|
|
### 49. Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`.
|
|
|
|
Lands after item 43. Today `- a` then `+ b`, or `1.` then `1)`, reads as one list; CommonMark reads
|
|
two (spec examples 301 and 302). Goal 5 settles it for the lossless flavour too: CommonMark spells
|
|
adjacent lists by changing the marker, so `adfToMarkdown` and `adfToPlainMarkdown` alternate `-` and
|
|
`*` between adjacent bullet lists and `.` and `)` between adjacent ordered lists, and
|
|
`!adf:listBreak` retires. `*` is the maintainer's pick (2026-10-04). Breaking, so it ships beside
|
|
item 43: `MIGRATION.md`'s Readings and Spellings tables gain their rows. Examples 301 and 302 lose
|
|
their `pending` exceptions, and the spelling leaves the README's "Four CommonMark spellings" bullet,
|
|
which counts one fewer.
|
|
|
|
### 61. Have the emitter ask the inline reader how a line reads back, in place of `line-escaping.ts` predicting it.
|
|
|
|
The comprehension panel's worst place: `escapeClaims` and `escapeClosedRuns` re-implement the
|
|
reader's view — flanking, code-span closers, link-definition openings, highlight flanking — and
|
|
only the property tests catch drift. It caps the panel's Locality score. The replacement runs in
|
|
time linear in the line: today `mergesWithSyntax`, `touchesSyntax` and `closesHeading` rescan a run
|
|
of one character from each of its characters.
|
|
|
|
### 52. Spell `colwidth` as a comma list, `colwidth="340,420"`.
|
|
|
|
A writer panel chose it on 2026-10-03, 5 of 7, over today's `colwidth="[340,420]"`. Breaking:
|
|
`MIGRATION.md`'s Spellings table gains its row.
|
|
|
|
### 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); lowercasing and then uppercasing folds it. Breaking, so it ships beside item 43:
|
|
`MIGRATION.md`'s Readings table gains its row. Its `pending` exceptions go, and its spelling leaves
|
|
the README's "Four CommonMark spellings" bullet, which counts one fewer.
|
|
|
|
### 60. Collect the questions `parse/` asks `emit/` into one named module.
|
|
|
|
`parse/` asks `emit/` through `commonMarkSpelling` and `openingLinkTakesDirective`, each imported
|
|
from where it happens to live. One module naming the questions keeps `docs/decisions.md` §The source
|
|
parts by ADF and format true as they grow.
|
|
|
|
### 59. Group the directive grammar into `src/markdown/directive/`, move `Read<T>` to `result.ts`, and move `Flavour` to `markdown/flavour.ts`.
|
|
|
|
Eight directive files sit across three directories, and the `markdown/` root holds 14 entries. HTML
|
|
needs `Read<T>` and `Flavour` out of the plain flavour and `markdown/`; it needs the carry and the
|
|
mark spellings too, which item 7 moves where it learns what HTML shares.
|
|
|
|
### 53. Put a block's `marks` spelling to the writer panel and adopt its pick.
|
|
|
|
Today `marks="[{\"attrs\":{\"mode\":\"wide\"},\"type\":\"breakout\"}]"`, the marks array as
|
|
escaped JSON. Breaking where the panel picks another spelling: `MIGRATION.md`'s Spellings table
|
|
gains its row.
|
|
|
|
### 62. Move the plain flavour's reading out of `parse/` and its writing out of `emit/` into `markdown/plain/`, so `emit/` no longer imports `plain/`.
|
|
|
|
Reading: the alert and task-marker reads in `parse/markdown-to-adf.ts`, the `mintTaskIds` call and
|
|
the `inlineLeaves` use. Writing: `spellPlainBlock`, `quotedUnder`, `tryTaskList` and `taskBlocks` in
|
|
`emit/adf-to-markdown.ts`. And `highlightDelimiter` and `highlightFlanking` move out of
|
|
`plain/conventions.ts`, which `emit/` imports them from; item 59 moves `Flavour`. Every
|
|
comprehension reader on 2026-10-03 named the plain flavour's spread across three directories.
|
|
|
|
### 50. Read `[](/url)` and `[]()` as CommonMark's empty link.
|
|
|
|
Both stay literal text today (spec examples 484 and 487). ADF holds no empty text node to carry a
|
|
link mark, so a link whose text is empty takes its URL as its text (the maintainer, 2026-10-04):
|
|
`[](/url)` reads as `/url` linked to `/url`. `[]()` has no URL to show; the chunk settles it by Goals
|
|
4 and 7. Breaking, so it ships beside item 43: `MIGRATION.md`'s Readings table gains its row. Its
|
|
`pending` exceptions go, and its spelling leaves the README's "Four CommonMark spellings" bullet,
|
|
which counts one fewer.
|
|
|
|
### 47. Open the README with what the package is, what it does and for whom.
|
|
|
|
It opens with the pre-launch rationale — Atlassian's REST APIs, `pf-editor-service/convert` being
|
|
decommissioned, a link to JRACLOUD-77436. The background goes entirely, no endpoint, ticket or "why"
|
|
note left. The badges are npm's version and the Gitea Actions status. The README names the lossy
|
|
pair, `adfToPlainMarkdown` and `plainMarkdownToAdf`, and the flavours it writes and reads — GitHub
|
|
Flavored Markdown's alerts and task lists, Obsidian Flavored Markdown's callouts — so a search for
|
|
any of these names finds the package.
|
|
|
|
### 73. Announce the package where someone needing an ADF converter already reads: JRACLOUD-77436, the Atlassian developer community and Stack Overflow's ADF-to-markdown questions.
|
|
|
|
Lands after `0.2.0` is published and items 71 and 72 land, so each post links the GitHub
|
|
repository and the comparison. We draft each post for the place it goes; the maintainer posts
|
|
them. Found while planning discoverability, 2026-10-04.
|
|
|
|
### 38. Spell a lone surrogate in a text node so it survives a UTF-8 encode.
|
|
|
|
`adfToMarkdown` emits it verbatim, so markdown stored as UTF-8 reads back U+FFFD; attribute values
|
|
already escape it.
|
|
|
|
### 48. Keep the release path publishing past npm's bypass-2FA token retirement.
|
|
|
|
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; its
|
|
replacement — trusted publishing over OIDC — supports GitHub-hosted Actions, GitLab.com's shared
|
|
runners and CircleCI's cloud, self-hosted runners planned without a date. Revisit: whether npm has
|
|
added Gitea or self-hosted OIDC, and otherwise whether the release moves to the staged publish —
|
|
which fits badly with publish-on-merge, and is the maintainer's trade to weigh. The Goals and G
|
|
cells are provisional: no README goal covers the release path.
|
|
|
|
### 46. Publish the bundle size in the README, failing the release pipeline when it drifts.
|
|
|
|
Lands after item 7, which changes it. The quantity is what a consumer downloads and loads: the
|
|
tarball `npm pack` produces, its unpacked `dist`, and the built JavaScript minified + gzipped — the
|
|
figure the competitors advertise (marklassian's "12kb") and the only apples-to-apples one, since
|
|
ours ships tsc's unminified output and no minifier yet (decide here whether to minify for the build
|
|
or report the unminified gzip). The figure lands in README §The package beside the "no runtime
|
|
dependencies" claim. Measured today, unminified: tarball 60.4 kB, unpacked 221.5 kB, JS gzipped 45.6
|
|
kB.
|
|
|
|
### 34. Read emphasis flanking by the whole character beside an astral symbol.
|
|
|
|
Check whether `line-escaping.ts`'s `charAt` and the parser's flanking read one UTF-16 unit beside an
|
|
astral symbol — a lone surrogate is neither punctuation nor symbol, where CommonMark reads `😀` as
|
|
punctuation — and, where they do, read the code point, with a fixture per direction.
|
|
|
|
### 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.
|
|
|
|
### 42. Trim a text leaf's trailing blanks in linear time.
|
|
|
|
`plain/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
|
|
`adfToPlainMarkdown`. Scan backward, as the expand title's trim does.
|
|
|
|
### 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 twelve functions that
|
|
mutate it and return `void`; `walk.leaf` alone is written in seven places. `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`, `deactivatedBefore` and `openingSpellableLink` and return
|
|
`void`, and `parseInlineContent` reads a flag `scanInline` leaves on it. The same shape recurs in
|
|
`mintTaskIds` (`plain/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`, `markPairings` and `markHighlights` (`inline-content.ts`), whose order changes the
|
|
output; and `nestIn` (`plain/adf-to-plain-markdown.ts`), which pushes into its caller's array.
|
|
|
|
### 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.
|
|
|
|
### 58. Port `ci.sh`, `publish.sh` and `docker-runner.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.
|
|
|
|
### 8. Ship a CLI.
|
|
|
|
The Goals and G cells are provisional: 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.
|