feat: support parsing existing package.json descriptions as markdown (#2132)

## PR Checklist

- [x] Addresses an existing open issue: fixes #1934
- [x] That issue was marked as [`status: accepting
prs`](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22)
- [x] Steps in
[CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/create-typescript-app/blob/main/.github/CONTRIBUTING.md)
were taken

## Overview

Makes parsing around HTML (`README.md`) vs. markdown (`package.json`)
descriptions smarter. [`marked`](https://marked.js.org) in inline mode
is used to parse existing `package.json` descriptions, before they're
checked against the README.md one.

Also normalizes the output `package.json`'s `description` to be plain
text, since neither GitHub nor npm support rich text
(#1934 (comment)).
Example improvement:
JoshuaKGoldberg/eslint-plugin-erasable-syntax-only@c43f07b

🎁

Author: JoshuaKGoldberg

package.json

@@ -54,6 +54,7 @@
 		"json5": "^2.2.3",
 		"lazy-value": "^3.0.0",
 		"lodash": "^4.17.21",
+		"marked": "^15.0.7",
 		"npm-user": "^6.1.1",
 		"object-strings-deep": "^0.1.1",
 		"parse-author": "^2.0.0",

pnpm-lock.yaml

@@ -185,7 +185,8 @@ export const base = createBase({
 		const getEmoji = lazyValue(async () => await readEmoji(getDescription));
 
 		const getDescription = lazyValue(
-			async () => await readDescription(getPackageData, getReadme),
+			async () =>
+				await readDescription(getPackageData, getReadme, getRepository),
 		);
 
 		const getDevelopmentDocumentation = lazyValue(

src/base.ts

@@ -5,8 +5,8 @@ import { z } from "zod";
 import { PackageJson } from "zod-package-json";
 
 import { base } from "../base.js";
+import { htmlToTextSafe } from "../utils/htmlToTextSafe.js";
 import { blockRemoveFiles } from "./blockRemoveFiles.js";
-import { htmlToTextSafe } from "./html/htmlToTextSafe.js";
 import { CommandPhase } from "./phases.js";
 
 const PackageJsonWithNullableScripts = PackageJson.partial().extend({

src/blocks/blockPackageJson.ts

@@ -43,7 +43,7 @@ describe("blockRepositorySettings", () => {
 		`);
 	});
 
-	test("with a long description", () => {
+	test("with a long HTML description", () => {
 		const creation = testBlock(blockRepositorySettings, {
 			options: {
 				...optionsBase,

src/blocks/blockRepositorySettings.test.ts

@@ -1,5 +1,5 @@
 import { base } from "../base.js";
-import { htmlToTextSafe } from "./html/htmlToTextSafe.js";
+import { htmlToTextSafe } from "../utils/htmlToTextSafe.js";
 
 export const blockRepositorySettings = base.createBlock({
 	about: {

src/blocks/blockRepositorySettings.ts

@@ -1,79 +1,112 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 
+import { packageData } from "../data/packageData.js";
 import { readDescription } from "./readDescription.js";
 
-const mockPackageDataDescription = vi.fn<() => string>();
-
-vi.mock("../data/packageData.js", () => ({
-	packageData: {
-		get description() {
-			return mockPackageDataDescription();
-		},
-	},
-}));
-
 describe(readDescription, () => {
 	it("returns undefined when the there is no package.json description", async () => {
 		const description = await readDescription(
 			() => Promise.resolve({}),
 			() => Promise.resolve(""),
+			() => Promise.resolve("other-repository"),
 		);
 
 		expect(description).toBeUndefined();
-		expect(mockPackageDataDescription).not.toHaveBeenCalled();
 	});
 
-	it("returns undefined when the description matches the current package.json description", async () => {
+	it("returns the README.md description when it matches the current package.json description", async () => {
 		const existing = "Same description.";
 
-		mockPackageDataDescription.mockReturnValueOnce(existing);
-
 		const description = await readDescription(
 			() => Promise.resolve({ description: existing }),
 			() => Promise.resolve(""),
+			() => Promise.resolve("other-repository"),
 		);
 
-		expect(description).toBeUndefined();
+		expect(description).toBe(existing);
 	});
 
-	it("returns the updated description when neither description nor name match the current package.json", async () => {
+	it("returns the updated package.json description when neither description nor name match the current package.json", async () => {
 		const updated = "Updated description.";
 
-		mockPackageDataDescription.mockReturnValueOnce("Existing description");
-
 		const description = await readDescription(
 			() => Promise.resolve({ description: updated }),
 			() => Promise.resolve(""),
+			() => Promise.resolve("other-repository"),
 		);
 
 		expect(description).toBe(updated);
 	});
 
-	it("uses the README.md HTML description when it matches what's inferred from package.json plus HTML tags", async () => {
+	it("returns the existing description when they are equal to crate-typescript-app's and the repository is create-typescript-app", async () => {
+		const description = await readDescription(
+			() => Promise.resolve({ description: packageData.description }),
+			() => Promise.resolve(`<p align="center">${packageData.description}</p>`),
+			() => Promise.resolve("create-typescript-app"),
+		);
+
+		expect(description).toBe(packageData.description);
+	});
+
+	it("returns undefined when the descriptions are create-typescript-app's and the repository is not", async () => {
+		const description = await readDescription(
+			() => Promise.resolve({ description: packageData.description }),
+			() => Promise.resolve(`<p align="center">${packageData.description}</p>`),
+			() => Promise.resolve("other-repository"),
+		);
+
+		expect(description).toBeUndefined();
+	});
+
+	it("uses a README.md HTML description when it matches plain text from package.json plus HTML tags", async () => {
 		const plaintext = "Updated description.";
 		const encoded = "Updated <code>description</code>.";
 
-		mockPackageDataDescription.mockReturnValueOnce("Existing description");
-
 		const description = await readDescription(
 			() => Promise.resolve({ description: plaintext }),
 			() => Promise.resolve(`<p align="center">${encoded}</p>`),
+			() => Promise.resolve("other-repository"),
 		);
 
 		expect(description).toBe(encoded);
 	});
 
-	it("uses the package.json description when the README.md HTML description doesn't match what's inferred from package.json plus HTML tags", async () => {
+	it("uses a README.md HTML description when it matches markdown from package.json plus HTML tags", async () => {
+		const markdown = "Before `inner` after.";
+		const html = `Before <a href="https://create.bingo"><code>inner</code></a> after.`;
+
+		const description = await readDescription(
+			() => Promise.resolve({ description: markdown }),
+			() => Promise.resolve(`<p align="center">${html}</p>`),
+			() => Promise.resolve("other-repository"),
+		);
+
+		expect(description).toBe(html);
+	});
+
+	it("uses a plain text package.json description when the README.md HTML description doesn't match what's inferred from package.json plus HTML tags", async () => {
 		const plaintext = "Updated description.";
 		const encoded = "Incorrect <code>description</code>.";
 
-		mockPackageDataDescription.mockReturnValueOnce("Existing description");
-
 		const description = await readDescription(
 			() => Promise.resolve({ description: plaintext }),
 			() => Promise.resolve(`<p align="center">${encoded}</p>`),
+			() => Promise.resolve("other-repository"),
 		);
 
 		expect(description).toBe(plaintext);
 	});
+
+	it("uses a markdown package.json description parsed to HTML when the README.md does not have a description and the package.json description is markdown", async () => {
+		const inPackageJson = "Updated _description_.";
+		const inReadme = "Incorrect <code>description</code>.";
+
+		const description = await readDescription(
+			() => Promise.resolve({ description: inPackageJson }),
+			() => Promise.resolve(`<p align="center">${inReadme}</p>`),
+			() => Promise.resolve("other-repository"),
+		);
+
+		expect(description).toBe("Updated <em>description</em>.");
+	});
 });

src/blocks/html/htmlToTextSafe.ts

@@ -1,22 +1,48 @@
+import { marked } from "marked";
+
 import { packageData } from "../data/packageData.js";
 import { PartialPackageData } from "../types.js";
+import { htmlToTextSafe } from "../utils/htmlToTextSafe.js";
 import { readDescriptionFromReadme } from "./readDescriptionFromReadme.js";
 
 export async function readDescription(
 	getPackageData: () => Promise<PartialPackageData>,
 	getReadme: () => Promise<string>,
+	getRepository: () => Promise<string | undefined>,
 ) {
-	const { description: inferred } = await getPackageData();
-	if (!inferred) {
+	// If we there is no package.json yet, this is probably setup mode.
+	const { description: fromPackageJson } = await getPackageData();
+	if (!fromPackageJson) {
 		return undefined;
 	}
 
-	const { description: existing } = packageData;
+	// If only a a package.json exists, this is probably transition mode.
+	// We can use the package.json's description as the only source of truth.
 	const fromReadme = await readDescriptionFromReadme(getReadme);
+	if (!fromReadme) {
+		return marked.parseInline(fromPackageJson);
+	}
+
+	// If the package.json is create-typescript-app's but the repository isn't,
+	// we're almost certainly in transition mode after cloning the template.
+	if (
+		(await getRepository()) !== "create-typescript-app" &&
+		fromPackageJson === packageData.description
+	) {
+		return undefined;
+	}
+
+	const fromPackageJsonNormalized = htmlToTextSafe(
+		await marked.parseInline(fromPackageJson),
+	);
+	const fromReadmeNormalized = htmlToTextSafe(fromReadme);
 
-	if (fromReadme?.replaceAll(/<\s*(?:\/\s*)?\w+\s*>/gu, "") === inferred) {
-		return fromReadme;
+	// If the package.json and README.md don't match, we prefer the package.json,
+	// as it's what is used in publishing to npm.
+	if (fromReadmeNormalized !== fromPackageJsonNormalized) {
+		return await marked.parseInline(fromPackageJson);
 	}
 
-	return existing === inferred ? undefined : inferred;
+	// Otherwise, if they do match, the README.md may have more rich HTML text.
+	return fromReadme;
 }

src/options/readDescription.test.ts

@@ -0,0 +1,13 @@
+import { convert } from "html-to-text";
+
+export function htmlToTextSafe(raw: string) {
+	return convert(raw, {
+		selectors: [
+			{
+				options: { ignoreHref: true },
+				selector: "a",
+			},
+		],
+		wordwrap: false,
+	});
+}