feat: allow description to safely include HTML tags (#1820)

## PR Checklist

- [x] Addresses an existing open issue: fixes #1819
- [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

Uses [`html-to-text`](https://www.npmjs.com/package/html-to-text) to
remove any HTML tags from descriptions.

This ended up being a fun exploration of defaulting. As suggested in the
issue, if the `README.md` has a CTA-style paragraph that strictly
matches the `package.json` after removing HTML tags, then it's used.

💖

Author: JoshuaKGoldberg

Diff for: package.json

@@ -49,6 +49,7 @@
 		"execa": "^9.5.2",
 		"git-remote-origin-url": "^4.0.0",
 		"git-url-parse": "^16.0.0",
+		"html-to-text": "^9.0.5",
 		"image-size": "^1.2.0",
 		"input-from-file": "0.1.0-alpha.4",
 		"input-from-file-json": "0.1.0-alpha.4",
@@ -79,6 +80,7 @@
 		"@release-it/conventional-changelog": "9.0.3",
 		"@types/eslint-plugin-markdown": "2.0.2",
 		"@types/git-url-parse": "9.0.3",
+		"@types/html-to-text": "^9.0.4",
 		"@types/js-yaml": "4.0.9",
 		"@types/node": "22.10.2",
 		"@types/parse-author": "2.0.3",

Diff for: pnpm-lock.yaml

@@ -15,6 +15,7 @@ import { readEmails } from "../shared/options/createOptionDefaults/readEmails.js
 import { readFunding } from "../shared/options/createOptionDefaults/readFunding.js";
 import { readGuide } from "../shared/options/createOptionDefaults/readGuide.js";
 import { readPackageData } from "../shared/packages.js";
+import { readFileSafe } from "../shared/readFileSafe.js";
 import { tryCatchLazyValueAsync } from "../shared/tryCatchLazyValueAsync.js";
 import { AllContributorsData } from "../shared/types.js";
 import { readDescription } from "./readDescription.js";
@@ -156,6 +157,8 @@ export const base = createBase({
 			)?.stdout?.toString();
 		});
 
+		const readme = lazyValue(async () => await readFileSafe("README.md", ""));
+
 		// TODO: Make these all use take
 
 		const gitDefaults = tryCatchLazyValueAsync(async () =>
@@ -196,7 +199,7 @@ export const base = createBase({
 			author,
 			bin: async () => (await packageData()).bin,
 			contributors: allContributors,
-			description: async () => await readDescription(packageData),
+			description: async () => await readDescription(packageData, readme),
 			documentation,
 			email: async () => readEmails(npmDefaults, packageAuthor),
 			funding: readFunding,
@@ -220,7 +223,7 @@ export const base = createBase({
 				options.repository ??
 				(await gitDefaults())?.name ??
 				(await packageData()).name,
-			...readDefaultsFromReadme(),
+			...readDefaultsFromReadme(readme),
 			version,
 		};
 	},

Diff for: src/next/base.ts

@@ -1,3 +1,4 @@
+import * as htmlToText from "html-to-text";
 import removeUndefinedObjects from "remove-undefined-objects";
 import sortPackageJson from "sort-package-json";
 import { z } from "zod";
@@ -44,6 +45,7 @@ export const blockPackageJson = base.createBlock({
 			...options.packageData?.devDependencies,
 			...addons.properties.devDependencies,
 		};
+		const description = htmlToText.convert(options.description);
 
 		return {
 			files: {
@@ -56,7 +58,7 @@ export const blockPackageJson = base.createBlock({
 							dependencies: Object.keys(dependencies).length
 								? dependencies
 								: undefined,
-							description: options.description,
+							description,
 							devDependencies: Object.keys(devDependencies).length
 								? devDependencies
 								: undefined,

Diff for: src/next/blocks/blockPackageJson.ts

@@ -1,10 +1,14 @@
+import * as htmlToText from "html-to-text";
+
 import { base } from "../base.js";
 
 export const blockRepositorySettings = base.createBlock({
 	about: {
 		name: "Repository Settings",
 	},
 	produce({ options }) {
+		const description = htmlToText.convert(options.description);
+
 		return {
 			requests: [
 				{
@@ -16,7 +20,7 @@ export const blockRepositorySettings = base.createBlock({
 							allow_rebase_merge: false,
 							allow_squash_merge: true,
 							delete_branch_on_merge: true,
-							description: options.description,
+							description,
 							has_wiki: false,
 							owner: options.owner,
 							repo: options.repository,

Diff for: src/next/blocks/blockRepositorySettings.ts

@@ -2,44 +2,68 @@ import { describe, expect, it, vi } from "vitest";
 
 import { readDescription } from "./readDescription.js";
 
-const mockSourcePackageJsonDescription = vi.fn<() => string>();
+const mockSourcePackageJson = vi.fn<() => string>();
 
 vi.mock("./blocks/sourcePackageJson", () => ({
 	sourcePackageJson: {
 		get description() {
-			return mockSourcePackageJsonDescription();
+			return mockSourcePackageJson();
 		},
 	},
 }));
 
-describe("finalize", () => {
+describe("readDescription", () => {
 	it("returns undefined when the description matches the current package.json description", async () => {
 		const existing = "Same description.";
 
-		mockSourcePackageJsonDescription.mockReturnValueOnce(existing);
+		mockSourcePackageJson.mockReturnValueOnce(existing);
 
-		const documentation = await readDescription(() =>
-			Promise.resolve({
-				description: existing,
-			}),
+		const description = await readDescription(
+			() => Promise.resolve({ description: existing }),
+			() => Promise.resolve(""),
 		);
 
-		expect(documentation).toBeUndefined();
+		expect(description).toBeUndefined();
 	});
 
 	it("returns the updated description when neither description nor name match the current package.json", async () => {
 		const updated = "Updated description.";
 
-		mockSourcePackageJsonDescription.mockReturnValueOnce(
-			"Existing description",
+		mockSourcePackageJson.mockReturnValueOnce("Existing description");
+
+		const description = await readDescription(
+			() => Promise.resolve({ description: updated }),
+			() => Promise.resolve(""),
 		);
 
-		const documentation = await readDescription(() =>
-			Promise.resolve({
-				description: updated,
-			}),
+		expect(description).toBe(updated);
+	});
+
+	it("uses the README.md HTML description when it matches what's inferred from package.json plus HTML tags", async () => {
+		const plaintext = "Updated description.";
+		const encoded = "Updated <code>description</code>.";
+
+		mockSourcePackageJson.mockReturnValueOnce("Existing description");
+
+		const description = await readDescription(
+			() => Promise.resolve({ description: plaintext }),
+			() => Promise.resolve(`<p align="center">${encoded}</p>`),
+		);
+
+		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 () => {
+		const plaintext = "Updated description.";
+		const encoded = "Incorrect <code>description</code>.";
+
+		mockSourcePackageJson.mockReturnValueOnce("Existing description");
+
+		const description = await readDescription(
+			() => Promise.resolve({ description: plaintext }),
+			() => Promise.resolve(`<p align="center">${encoded}</p>`),
 		);
 
-		expect(documentation).toBe(updated);
+		expect(description).toBe(plaintext);
 	});
 });

Diff for: src/next/readDescription.test.ts

@@ -1,11 +1,22 @@
 import { PartialPackageData } from "../shared/types.js";
 import { sourcePackageJson } from "./blocks/sourcePackageJson.js";
+import { readDescriptionFromReadme } from "./readDescriptionFromReadme.js";
 
 export async function readDescription(
 	getPackageData: () => Promise<PartialPackageData>,
+	getReadme: () => Promise<string>,
 ) {
 	const { description: inferred } = await getPackageData();
+	if (!inferred) {
+		return undefined;
+	}
+
 	const { description: existing } = sourcePackageJson;
+	const fromReadme = await readDescriptionFromReadme(getReadme);
+
+	if (fromReadme?.replaceAll(/<\s*(?:\/\s*)?\w+\s*>/gu, "") === inferred) {
+		return fromReadme;
+	}
 
 	return existing === inferred ? undefined : inferred;
 }