Answer the prose review's second round and the product-owner review's second
This commit is contained in:
@@ -143,7 +143,7 @@ Per chunk:
|
|||||||
result exists for the commit under review, or when the diff since that result cannot affect
|
result exists for the commit under review, or when the diff since that result cannot affect
|
||||||
it (docs-only) — re-run only what its own findings or fixes invalidate.
|
it (docs-only) — re-run only what its own findings or fixes invalidate.
|
||||||
3. Merge the PR (standing authorization, this repo only, granted by the maintainer through the
|
3. Merge the PR (standing authorization, this repo only, granted by the maintainer through the
|
||||||
`0.2.0` release), delete the chunk's items from `todo.md` — what a consumer sees of it is
|
`0.2.0` release), delete the chunk's items from `todo.md` — what a consumer sees of them is
|
||||||
reworded for them into `CHANGELOG.md`'s `## Unreleased` — report, stop.
|
reworded for them into `CHANGELOG.md`'s `## Unreleased` — report, stop.
|
||||||
|
|
||||||
Reserved for the maintainer whatever any rule here says: changing `version` in `package.json` (a
|
Reserved for the maintainer whatever any rule here says: changing `version` in `package.json` (a
|
||||||
@@ -172,7 +172,7 @@ The verdict lands in `docs/decisions.md`.
|
|||||||
|
|
||||||
### Findings, numbers and empty releases
|
### Findings, numbers and empty releases
|
||||||
|
|
||||||
- A finding inside the chunk's items is fixed in the chunk. Outside it, a new `todo.md` item, always
|
- A finding inside the chunk's items is fixed in the chunk. Outside them, a new `todo.md` item, always
|
||||||
in a release, weighed against every item on that release by the personas and `docs/decisions.md`
|
in a release, weighed against every item on that release by the personas and `docs/decisions.md`
|
||||||
§Plain markdown is a flavour of the grammar through §Names stay text — an item it outweighs moves
|
§Plain markdown is a flavour of the grammar through §Names stay text — an item it outweighs moves
|
||||||
later. A weighing no entry decides is asked as a gap.
|
later. A weighing no entry decides is asked as a gap.
|
||||||
|
|||||||
@@ -38,8 +38,8 @@ The most useful ADF conversion library available, by these goals in priority ord
|
|||||||
## Audience
|
## Audience
|
||||||
|
|
||||||
Application developers embedding the library, in four personas. All four rely on the guarantees
|
Application developers embedding the library, in four personas. All four rely on the guarantees
|
||||||
below and on `code` being a closed list; none may rely on an error message's wording, which is
|
below and on an error's `code` being a closed list; none may rely on an error message's wording,
|
||||||
free text.
|
which is free text.
|
||||||
|
|
||||||
- **Viewer/editor app** — shows a document, lets a human edit, posts it back. Relies on the
|
- **Viewer/editor app** — shows a document, lets a human edit, posts it back. Relies on the
|
||||||
round-trip holding for whatever the site's editor wrote, unknown node types included, and on a
|
round-trip holding for whatever the site's editor wrote, unknown node types included, and on a
|
||||||
@@ -70,8 +70,8 @@ if (result.ok) {
|
|||||||
```
|
```
|
||||||
|
|
||||||
Serves Goals 1, 2 and 7. Pure functions, each taking a whole document and returning a whole
|
Serves Goals 1, 2 and 7. Pure functions, each taking a whole document and returning a whole
|
||||||
result; no I/O, no configuration. Every conversion goes through ADF, so `markdownToHtml` keeps
|
result; no I/O, no configuration. `markdownToHtml` and `htmlToMarkdown` convert through ADF, so
|
||||||
exactly what ADF holds.
|
they drop whatever ADF cannot hold.
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
adfToMarkdown(doc: AdfDocument): Result<string>
|
adfToMarkdown(doc: AdfDocument): Result<string>
|
||||||
@@ -83,8 +83,8 @@ plainMarkdownToAdf(markdown: string): Result<AdfDocument, ParseError>
|
|||||||
|
|
||||||
adfToHtml(doc: AdfDocument): Result<string> // 0.2.0
|
adfToHtml(doc: AdfDocument): Result<string> // 0.2.0
|
||||||
htmlToAdf(html: string): Result<AdfDocument, ParseError> // 0.2.0
|
htmlToAdf(html: string): Result<AdfDocument, ParseError> // 0.2.0
|
||||||
markdownToHtml(markdown: string): Result<string> // 0.2.0, via ADF
|
markdownToHtml(markdown: string): Result<string> // 0.2.0
|
||||||
htmlToMarkdown(html: string): Result<string> // 0.2.0, via ADF
|
htmlToMarkdown(html: string): Result<string> // 0.2.0
|
||||||
```
|
```
|
||||||
|
|
||||||
`Result<T>` is `{ ok: true; value: T } | { ok: false; error: ConvertError }` — nothing throws.
|
`Result<T>` is `{ ok: true; value: T } | { ok: false; error: ConvertError }` — nothing throws.
|
||||||
@@ -201,9 +201,9 @@ Serves Goals 1, 3 and 4.
|
|||||||
|
|
||||||
- `markdownToAdf(adfToMarkdown(doc))` equals `doc` — unknown node types included, carried opaquely
|
- `markdownToAdf(adfToMarkdown(doc))` equals `doc` — unknown node types included, carried opaquely
|
||||||
([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#unknown-nodes-ride-the-carry)).
|
([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#unknown-nodes-ride-the-carry)).
|
||||||
- Markdown means what the CommonMark spec says — and, at `0.2.0`, well-formed HTML what the HTML
|
- Markdown this library reads, and markdown it writes, means what the CommonMark spec says; from
|
||||||
standard parses — both in what this library reads and in what a conforming parser reads back
|
`0.2.0`, well-formed HTML means what the HTML standard says, read or written. The bullets below
|
||||||
from its output; the bullets below name every exception.
|
name every exception.
|
||||||
- Plain CommonMark is valid input to `markdownToAdf` apart from the raw HTML `unmappable-html`
|
- Plain CommonMark is valid input to `markdownToAdf` apart from the raw HTML `unmappable-html`
|
||||||
names, with three carve-outs — literal text matching directive, pipe-table or strikethrough
|
names, with three carve-outs — literal text matching directive, pipe-table or strikethrough
|
||||||
syntax is claimed (escapable — `spec/flavour.md`) — and one gap: a CommonMark image fits only as
|
syntax is claimed (escapable — `spec/flavour.md`) — and one gap: a CommonMark image fits only as
|
||||||
@@ -242,7 +242,7 @@ Serves Goals 1, 3 and 4.
|
|||||||
## The package
|
## The package
|
||||||
|
|
||||||
Serves Goal 7. ESM only, no runtime dependencies, public npm. Built JavaScript with `.d.ts`
|
Serves Goal 7. ESM only, no runtime dependencies, public npm. Built JavaScript with `.d.ts`
|
||||||
beside it. Pure ECMAScript at an ES2022 baseline, reaching for no host API; the test suite runs under Node,
|
beside it. Pure ECMAScript at an ES2022 baseline, reaching for no host API; the test suite runs
|
||||||
Deno and Bun, and a headless Firefox converts the corpus through the built entrypoint.
|
under Node, Deno and Bun, and a headless Firefox converts the corpus through the built entrypoint.
|
||||||
Contract: [`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#any-es2022-engine), §Any
|
Contract: [`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#any-es2022-engine), §Any
|
||||||
ES2022 engine to §Public on npm.
|
ES2022 engine to §Public on npm.
|
||||||
|
|||||||
@@ -65,9 +65,10 @@
|
|||||||
`description` naming both, the lossy pair, and the flavours it writes and reads by name — GitHub
|
`description` naming both, the lossy pair, and the flavours it writes and reads by name — GitHub
|
||||||
Flavored Markdown's alerts and task lists, Obsidian Flavored Markdown's callouts — so a search for
|
Flavored Markdown's alerts and task lists, Obsidian Flavored Markdown's callouts — so a search for
|
||||||
either finds the package.
|
either finds the package.
|
||||||
- **44 — Delete `AGENTS.md` §7's empty-release bullet, leaving the maintainer's global working loop
|
- **44 — Cut `AGENTS.md` §7's empty-release bullet to what the maintainer's global working loop
|
||||||
to rule it.** "An earliest release with no items left and nothing shipped toward it is planned as
|
leaves open.** The bullet restates that loop's rule for an empty release, in a sentence
|
||||||
the chunk" restates that loop, in a sentence its own prose rules ban.
|
`~/.claude/CLAUDE.md` → "Prose" bans; keep only its weighing by the personas and
|
||||||
|
`docs/decisions.md`, which the global loop does not hold.
|
||||||
|
|
||||||
## 0.3.0
|
## 0.3.0
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user