Copy the README tagline to the npm description at publish; name Jira and Confluence in it

README.md

@@ -3,8 +3,10 @@
 [![npm](https://img.shields.io/npm/v/@larvit/adf-codec)](https://www.npmjs.com/package/@larvit/adf-codec)
 [![CI](https://github.com/larvit/adf-codec/actions/workflows/ci.yml/badge.svg)](https://github.com/larvit/adf-codec/actions/workflows/ci.yml)
 
-Convert between ADF (Atlassian Document Format) and markdown or HTML. For application developers
-whose app shows, edits, exports or generates the rich text Atlassian products store as ADF.
+Convert between ADF (Atlassian Document Format, the rich text of Jira and Confluence) and markdown or HTML.
+
+For application developers whose app shows, edits, exports or generates the rich text Atlassian
+products store as ADF.
 
 ## Main functionality
 
@@ -784,6 +786,8 @@ All three commands need only Docker, git and bash 5.
 - `./mutation-tests/run.sh [<base>]` mutation-tests the lines changed since `<base>`, `origin/main`
   by default, in source files git tracks. It needs 6 GB of memory for Docker, and lists the mutants
   that survived. Survivors don't fail it; a mutant whose test run crashed does.
+- The README's first paragraph after the badges is the npm description: `./publish.sh` copies it to
+  `package.json`. Keep it plain text; `./ci.sh` fails where it isn't.
 
 ## Links
 

ci.sh

@@ -61,6 +61,7 @@ leg "tests ($deno_image)" in_image "$deno_image" deno test --allow-env=PROPERTY_
 leg "tests ($bun_image)" in_image "$bun_image" bun test src/
 leg "corpus-gathering tests ($node_image)" in_image "$node_image" node --test corpus-gathering/
 leg "feature table tests ($node_image)" in_image "$node_image" node --test feature-table/
+leg "release tooling tests ($node_image)" in_image "$node_image" node --test release-tooling/
 
 leg "build ($node_image)" in_image "$node_image" npm run build
 leg "feature table is current ($node_image)" in_image "$node_image" node feature-table/build.mjs --check

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@larvit/adf-codec",
   "version": "0.3.0",
-  "description": "Convert Atlassian Document Format (ADF), the rich text of Jira and Confluence, to and from markdown, with a lossless round-trip, and to HTML. No React, no Atlaskit, no runtime dependencies: runs in Node, Forge, Deno, Bun and browsers.",
+  "description": "Convert between ADF (Atlassian Document Format, the rich text of Jira and Confluence) and markdown or HTML.",
   "keywords": [
     "adf",
     "adf-to-html",

publish.sh

@@ -35,6 +35,8 @@ if [ -z "$published" ]; then
   : "${NPM_TOKEN:?the publish needs NPM_TOKEN}"
   leg "install ($node_image)" in_image "$node_image" npm ci
   leg "build ($node_image)" in_image "$node_image" npm run build
+  # npmjs shows the README's tagline, which package.json's description is overwritten with here.
+  leg "copy the README tagline to the description ($node_image)" in_image "$node_image" node release-tooling/write-description.mjs
   leg "publish $name@$version ($node_image)" \
     docker run --rm -u "$(id -u):$(id -g)" -e HOME=/tmp -e NPM_TOKEN -v "$PWD:/app" -w /app --entrypoint sh "$node_image" -c \
     'printf "//registry.npmjs.org/:_authToken=%s\n" "$NPM_TOKEN" > "$HOME/.npmrc" && npm publish --access public'

release-tooling/tagline.mjs

@@ -0,0 +1,12 @@
+const markup = /[`[\]*_<>]/
+
+// The README's first paragraph after the title and the badges.
+export function readmeTagline(readme) {
+  const lines = readme.split('\n').filter((line) => !line.startsWith('# ') && !line.startsWith('[!['))
+  const start = lines.findIndex((line) => line.trim() !== '')
+  if (start === -1 || lines[start].startsWith('#')) return { error: 'README.md has no tagline paragraph before its first section', ok: false }
+  const end = lines.findIndex((line, index) => index > start && line.trim() === '')
+  const tagline = lines.slice(start, end === -1 ? undefined : end).map((line) => line.trim()).join(' ')
+  if (markup.test(tagline)) return { error: `the README tagline is plain text, since npm shows it as is: ${tagline}`, ok: false }
+  return { ok: true, value: tagline }
+}

release-tooling/tagline.test.mjs

@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { test } from 'node:test'
+
+import { readmeTagline } from './tagline.mjs'
+
+const title = '# @larvit/pkg — a title\n\n[![npm](https://img.example/npm.svg)](https://example.com)\n[![CI](https://img.example/ci.svg)](https://example.com)\n\n'
+
+test('is the first paragraph after the title and the badges', () => {
+  assert.deepEqual(readmeTagline(`${title}Convert A to B.\n\nFor people who need it.\n\n## Install\n`), { ok: true, value: 'Convert A to B.' })
+})
+
+test('joins a paragraph wrapped over lines with single spaces', () => {
+  assert.deepEqual(readmeTagline(`${title}Convert A to B,\nand back.\n\nMore.\n`), { ok: true, value: 'Convert A to B, and back.' })
+})
+
+test('refuses a README with no paragraph before its first section', () => {
+  assert.equal(readmeTagline(`${title}## Install\n`).ok, false)
+})
+
+test('refuses markup, which npm would show as raw characters', () => {
+  for (const markup of ['`code`', '[link](https://example.com)', '**bold**', '_em_', '<b>x</b>']) {
+    assert.equal(readmeTagline(`${title}Convert ${markup}.\n`).ok, false, markup)
+  }
+})
+
+test('reads the real README', () => {
+  const tagline = readmeTagline(readFileSync(new URL('../README.md', import.meta.url), 'utf8'))
+  assert.ok(tagline.ok, tagline.error)
+  assert.ok(tagline.value.includes('Jira'))
+})

release-tooling/write-description.mjs

@@ -0,0 +1,12 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+
+import { readmeTagline } from './tagline.mjs'
+
+const packagePath = new URL('../package.json', import.meta.url)
+const tagline = readmeTagline(readFileSync(new URL('../README.md', import.meta.url), 'utf8'))
+if (!tagline.ok) {
+  console.error(tagline.error)
+  process.exit(1)
+}
+const manifest = JSON.parse(readFileSync(packagePath, 'utf8'))
+writeFileSync(packagePath, `${JSON.stringify({ ...manifest, description: tagline.value }, null, 2)}\n`)