shipseal 0.0.5 → 0.0.7

package/README.md

@@ -49,7 +49,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
         with: { fetch-depth: 0 }
-      - uses: akii09/shipseal@v1
+      - uses: akii09/shipseal@v0.0.7
         env: { GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" }
 ```
 

package/dist/cli.js

@@ -307,8 +307,11 @@ function deterministicCopy(facts, maxHighlights = 4) {
 	const features = (facts.release?.features ?? []).map((item) => item.value);
 	const fixes = (facts.release?.fixes ?? []).map((item) => item.value);
 	const breaking = (facts.release?.breaking ?? []).map((item) => item.value);
-	const headlineSource = breaking[0] ?? features[0] ?? fixes[0];
-	const headline = headlineSource !== void 0 ? cleanLine(firstSentence(headlineSource)) : version === void 0 ? name : `${name} ${version}`;
+	const headline = [
+		...breaking,
+		...features,
+		...fixes
+	].map((line) => cleanLine(firstSentence(line))).find((line) => line.length <= HEADLINE_MAX_CHARS) ?? (version === void 0 ? name : `${name} ${version}`);
 	const tagline = facts.project.tagline?.value;
 	const subheadline = tagline !== void 0 && tagline.length > 0 ? cleanLine(tagline) : cleanLine(features[1] ?? fixes[1] ?? fixes[0] ?? `What's new in ${version ?? name}`);
 	const highlights = [];
@@ -319,12 +322,27 @@ function deterministicCopy(facts, maxHighlights = 4) {
 	for (const line of breaking) addHighlight(line, "Breaking: ");
 	for (const line of features) addHighlight(line);
 	for (const line of fixes) addHighlight(line);
-	return {
+	const copy = {
 		headline,
 		subheadline,
 		highlights,
 		cta: ctaFor(facts)
 	};
+	const snippet = facts.release?.codeSnippet?.value.code;
+	if (snippet !== void 0 && isInstallOnly(snippet)) copy.codeTitle = "Get started";
+	return copy;
+}
+/**
+* Is this snippet nothing but install commands?
+*
+* Pairing "npm i thing" with a release headline reads as though the release was about
+* installing, which is how v0.0.6 shipped a bug-fix headline over the README's install block.
+* Install commands are still worth showing, they just need their own title.
+*/
+const INSTALL_COMMAND = /^\s*(?:\$\s*)?(?:npm\s+(?:i|install|add)|pnpm\s+(?:i|install|add|dlx)|yarn\s+(?:add|install)|bun\s+(?:a|add|install)|npx|deno\s+add|pip\s+install|cargo\s+add|go\s+get|gem\s+install|brew\s+install)\b/;
+function isInstallOnly(code) {
+	const lines = code.split("\n").map((line) => line.replace(/\s+#.*$/, "").trim()).filter((line) => line.length > 0 && !line.startsWith("#"));
+	return lines.length > 0 && lines.every((line) => INSTALL_COMMAND.test(line));
 }
 function formatCount$1(value) {
 	return value.toLocaleString("en-US");
@@ -363,6 +381,12 @@ function firstSentence(text) {
 	const collapsed = text.replace(/\s+/g, " ").trim();
 	return /^(.+?[.?!])\s+[A-Z]/.exec(collapsed)?.[1] ?? collapsed;
 }
+/**
+* Longest headline that fits two lines at the minimum font size on a 1200 wide card.
+* Measured rather than guessed: §13.1 originally said 48, which rejects most real changelog
+* sentences, and the fitting pass comfortably handles more.
+*/
+const HEADLINE_MAX_CHARS = 72;
 function cleanLine(text) {
 	const stripped = text.replace(/\s*\u2014\s*/g, ": ").replace(/\s+\u2013\s+/g, ", ").replaceAll("–", "-").replaceAll("!", ".").replace(/\s+/g, " ").trim();
 	const noTrail = stripped.endsWith(".") ? stripped.slice(0, -1) : stripped;
@@ -579,7 +603,7 @@ const codeCard = {
 		});
 		return {
 			props: {
-				headline: copy.headline,
+				headline: copy.codeTitle ?? copy.headline,
 				headingFamily: brand.fonts.heading.family,
 				monoFamily: brand.fonts.mono.family,
 				headingWeight: brand.fonts.heading.weight,
@@ -1460,7 +1484,9 @@ const releaseHighlights = {
 					style: {
 						display: "flex",
 						flexDirection: "column",
-						gap: 16
+						flexGrow: 1,
+						justifyContent: props.highlights.length > 2 ? "flex-start" : "center",
+						gap: props.highlights.length > 2 ? 16 : 20
 					},
 					children: props.highlights.map((line, index) => {
 						const fitted = ctx.fitted[`highlight-${String(index)}`];
@@ -1684,6 +1710,20 @@ async function copyForTemplate(templateId, copy, facts, theme) {
 	};
 }
 
+//#endregion
+//#region src/facts/fact.ts
+function fact(value, provenance) {
+	const fetchedAt = provenance.fetchedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		value,
+		provenance: {
+			source: provenance.source,
+			ref: provenance.ref,
+			fetchedAt
+		}
+	};
+}
+
 //#endregion
 //#region src/facts/merge.ts
 function mergeFacts(parts) {
@@ -1756,20 +1796,6 @@ function isCompleteRelease(release) {
 	return release.version !== void 0 && release.tag !== void 0 && release.date !== void 0;
 }
 
-//#endregion
-//#region src/facts/fact.ts
-function fact(value, provenance) {
-	const fetchedAt = provenance.fetchedAt ?? (/* @__PURE__ */ new Date()).toISOString();
-	return {
-		value,
-		provenance: {
-			source: provenance.source,
-			ref: provenance.ref,
-			fetchedAt
-		}
-	};
-}
-
 //#endregion
 //#region src/sources/bench-file.ts
 const metricSchema = z.object({
@@ -1844,6 +1870,117 @@ async function collectBenchFile(cwd, filePath = ".shipseal/bench.json") {
 	return { bench };
 }
 
+//#endregion
+//#region src/sources/readme.ts
+async function collectReadme(cwd) {
+	let markdown;
+	try {
+		markdown = await readFile(join(cwd, "README.md"), "utf8");
+	} catch {
+		return {};
+	}
+	const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const out = {};
+	const h1 = extractH1(markdown);
+	const tagline = extractTagline(markdown);
+	const snippet = extractFirstCodeFence(markdown);
+	const project = {};
+	if (h1 !== void 0) project.name = fact(h1, {
+		source: "readme",
+		ref: "README.md H1",
+		fetchedAt
+	});
+	if (tagline !== void 0) project.tagline = fact(tagline, {
+		source: "readme",
+		ref: "README.md first paragraph",
+		fetchedAt
+	});
+	if (project.name !== void 0 || project.tagline !== void 0) out.project = project;
+	if (snippet !== void 0) out.release = { codeSnippet: fact(snippet, {
+		source: "readme",
+		ref: "README.md first fenced code block",
+		fetchedAt
+	}) };
+	return out;
+}
+async function collectConfiguredSnippet(cwd, spec) {
+	const parsed = parseSnippetSpec(spec);
+	if (parsed === void 0) return {};
+	let contents;
+	try {
+		contents = await readFile(join(cwd, parsed.path), "utf8");
+	} catch {
+		return {};
+	}
+	const slice = contents.split(/\r?\n/).slice(parsed.start - 1, parsed.end).join("\n");
+	const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
+	return { release: { codeSnippet: fact({
+		code: slice,
+		lang: langFromPath(parsed.path)
+	}, {
+		source: "user-config",
+		ref: spec,
+		fetchedAt
+	}) } };
+}
+/**
+* Strip fenced code and HTML before reading prose out of a README.
+*
+* Skipping blocks that merely *start* with a fence is not enough. A `#` comment inside a YAML
+* example reads as a markdown H1, and a blank line inside a fence makes its body look like a
+* paragraph. Shipseal's own README hit both: the detected name became
+* ".github/workflows/shipseal.yml" and the tagline became a chunk of workflow YAML.
+*/
+function stripNonProse(markdown) {
+	return markdown.replace(/```[\s\S]*?```/g, "").replace(/~~~[\s\S]*?~~~/g, "").replace(/<[^>]+>/g, "");
+}
+function extractH1(markdown) {
+	const heading = /^#\s+(.+)$/m.exec(stripNonProse(markdown))?.[1];
+	if (heading === void 0) return;
+	return heading.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").trim();
+}
+function extractTagline(markdown) {
+	const prose = stripNonProse(markdown);
+	const h1 = /^#\s+.+$/m.exec(prose);
+	const start = h1 === null ? 0 : (h1.index ?? 0) + h1[0].length;
+	for (const block of prose.slice(start).split(/\n\s*\n/)) {
+		const cleaned = stripBadges(block).trim();
+		if (cleaned.length >= 20 && !cleaned.startsWith("#") && !cleaned.startsWith("```")) return cleaned;
+	}
+}
+function extractFirstCodeFence(markdown) {
+	const match = /```([a-zA-Z0-9+-]+)\n([\s\S]*?)```/.exec(markdown);
+	if (match === null || match[1] === void 0 || match[2] === void 0) return;
+	return {
+		lang: match[1],
+		code: match[2].replace(/\n$/, "")
+	};
+}
+function parseSnippetSpec(spec) {
+	const match = /^(?<path>.+)#L(?<start>\d+)(?:-L(?<end>\d+))?$/.exec(spec);
+	if (match === null || match.groups === void 0) return;
+	const path = match.groups.path;
+	const start = Number.parseInt(match.groups.start ?? "0", 10);
+	const end = Number.parseInt(match.groups.end ?? match.groups.start ?? "0", 10);
+	if (path === void 0 || start < 1 || end < start) return;
+	return {
+		path,
+		start,
+		end
+	};
+}
+function langFromPath(path) {
+	const ext = extname(path).replace(".", "");
+	if (ext === "ts") return "ts";
+	if (ext === "tsx") return "tsx";
+	if (ext === "js" || ext === "mjs" || ext === "cjs") return "js";
+	if (ext === "jsx") return "jsx";
+	return ext.length > 0 ? ext : "text";
+}
+function stripBadges(text) {
+	return text.replace(/\[!\[[^\]]*]\([^)]+\)]\([^)]+\)/g, "").replace(/!\[[^\]]*]\([^)]+\)/g, "").replace(/<img[^>]*>/gi, "").replace(/<[^>]+>/g, "").replace(/\s+/g, " ").trim();
+}
+
 //#endregion
 //#region src/sources/changelog.ts
 async function collectChangelog(cwd, version, changelogPath = "CHANGELOG.md") {
@@ -1891,6 +2028,15 @@ async function collectChangelog(cwd, version, changelogPath = "CHANGELOG.md") {
 		fixes,
 		breaking
 	} };
+	const snippet = extractFirstCodeFence(section.body);
+	if (snippet !== void 0) out.release = {
+		...out.release,
+		codeSnippet: fact(snippet, {
+			source: "changelog",
+			ref: `${changelogPath} ${section.heading} first fenced code block`,
+			fetchedAt
+		})
+	};
 	if (section.date !== void 0) out.release = {
 		...out.release,
 		date: fact(section.date, {
@@ -2277,6 +2423,7 @@ function lastPageFromLink(link) {
 //#endregion
 //#region src/sources/npm.ts
 const API_ROOT = "https://api.npmjs.org/downloads/point/last-week";
+const REGISTRY_ROOT = "https://registry.npmjs.org";
 const pointSchema = z.object({
 	downloads: z.number().int().nonnegative(),
 	start: z.string().optional(),
@@ -2314,6 +2461,31 @@ async function npmGet(url, fetchImpl, cache) {
 	cache.set(url, json);
 	return json;
 }
+/**
+* Is this name actually published?
+*
+* The downloads endpoint cannot answer this: it 404s for a package published minutes ago that
+* has no download data yet, which is exactly the case a first release is in. The registry
+* document is the authority.
+*
+* Only a definitive 404 counts as "no". A network error, a rate limit or anything else returns
+* undefined, so an unreachable registry never removes a call to action that was probably right.
+*/
+async function npmPackageExists(name, fetchImpl = fetch) {
+	const trimmed = name.trim();
+	if (trimmed.length === 0) return false;
+	let response;
+	try {
+		response = await fetchImpl(`${REGISTRY_ROOT}/${encodeURIComponent(trimmed)}`, {
+			method: "HEAD",
+			headers: { accept: "application/json" }
+		});
+	} catch {
+		return;
+	}
+	if (response.status === 404) return false;
+	return response.ok ? true : void 0;
+}
 
 //#endregion
 //#region src/sources/package-json.ts
@@ -2343,9 +2515,10 @@ async function collectPackageJson(cwd, packagePath = "package.json") {
 	const pkg = pkgSchema.safeParse(parsed);
 	if (!pkg.success) return {};
 	const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
-	const project = { name: fact(stripScope$1(pkg.data.name ?? basenameFromPath(cwd)), {
+	const rawName = pkg.data.private === true ? void 0 : pkg.data.name;
+	const project = { name: fact(stripScope$1(rawName ?? basenameFromPath(cwd)), {
 		source: "package-json",
-		ref: `${packagePath}#name`,
+		ref: rawName === void 0 ? `${packagePath} directory name` : `${packagePath}#name`,
 		fetchedAt
 	}) };
 	if (pkg.data.description !== void 0 && pkg.data.description.length > 0) project.tagline = fact(pkg.data.description, {
@@ -2409,117 +2582,6 @@ function normalizeGitUrl$1(url) {
 	return url.replace(/^git\+/, "").replace(/\.git$/, "");
 }
 
-//#endregion
-//#region src/sources/readme.ts
-async function collectReadme(cwd) {
-	let markdown;
-	try {
-		markdown = await readFile(join(cwd, "README.md"), "utf8");
-	} catch {
-		return {};
-	}
-	const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
-	const out = {};
-	const h1 = extractH1(markdown);
-	const tagline = extractTagline(markdown);
-	const snippet = extractFirstCodeFence(markdown);
-	const project = {};
-	if (h1 !== void 0) project.name = fact(h1, {
-		source: "readme",
-		ref: "README.md H1",
-		fetchedAt
-	});
-	if (tagline !== void 0) project.tagline = fact(tagline, {
-		source: "readme",
-		ref: "README.md first paragraph",
-		fetchedAt
-	});
-	if (project.name !== void 0 || project.tagline !== void 0) out.project = project;
-	if (snippet !== void 0) out.release = { codeSnippet: fact(snippet, {
-		source: "readme",
-		ref: "README.md first fenced code block",
-		fetchedAt
-	}) };
-	return out;
-}
-async function collectConfiguredSnippet(cwd, spec) {
-	const parsed = parseSnippetSpec(spec);
-	if (parsed === void 0) return {};
-	let contents;
-	try {
-		contents = await readFile(join(cwd, parsed.path), "utf8");
-	} catch {
-		return {};
-	}
-	const slice = contents.split(/\r?\n/).slice(parsed.start - 1, parsed.end).join("\n");
-	const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
-	return { release: { codeSnippet: fact({
-		code: slice,
-		lang: langFromPath(parsed.path)
-	}, {
-		source: "user-config",
-		ref: spec,
-		fetchedAt
-	}) } };
-}
-/**
-* Strip fenced code and HTML before reading prose out of a README.
-*
-* Skipping blocks that merely *start* with a fence is not enough. A `#` comment inside a YAML
-* example reads as a markdown H1, and a blank line inside a fence makes its body look like a
-* paragraph. Shipseal's own README hit both: the detected name became
-* ".github/workflows/shipseal.yml" and the tagline became a chunk of workflow YAML.
-*/
-function stripNonProse(markdown) {
-	return markdown.replace(/```[\s\S]*?```/g, "").replace(/~~~[\s\S]*?~~~/g, "").replace(/<[^>]+>/g, "");
-}
-function extractH1(markdown) {
-	const heading = /^#\s+(.+)$/m.exec(stripNonProse(markdown))?.[1];
-	if (heading === void 0) return;
-	return heading.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").trim();
-}
-function extractTagline(markdown) {
-	const prose = stripNonProse(markdown);
-	const h1 = /^#\s+.+$/m.exec(prose);
-	const start = h1 === null ? 0 : (h1.index ?? 0) + h1[0].length;
-	for (const block of prose.slice(start).split(/\n\s*\n/)) {
-		const cleaned = stripBadges(block).trim();
-		if (cleaned.length >= 20 && !cleaned.startsWith("#") && !cleaned.startsWith("```")) return cleaned;
-	}
-}
-function extractFirstCodeFence(markdown) {
-	const match = /```([a-zA-Z0-9+-]+)\n([\s\S]*?)```/.exec(markdown);
-	if (match === null || match[1] === void 0 || match[2] === void 0) return;
-	return {
-		lang: match[1],
-		code: match[2].replace(/\n$/, "")
-	};
-}
-function parseSnippetSpec(spec) {
-	const match = /^(?<path>.+)#L(?<start>\d+)(?:-L(?<end>\d+))?$/.exec(spec);
-	if (match === null || match.groups === void 0) return;
-	const path = match.groups.path;
-	const start = Number.parseInt(match.groups.start ?? "0", 10);
-	const end = Number.parseInt(match.groups.end ?? match.groups.start ?? "0", 10);
-	if (path === void 0 || start < 1 || end < start) return;
-	return {
-		path,
-		start,
-		end
-	};
-}
-function langFromPath(path) {
-	const ext = extname(path).replace(".", "");
-	if (ext === "ts") return "ts";
-	if (ext === "tsx") return "tsx";
-	if (ext === "js" || ext === "mjs" || ext === "cjs") return "js";
-	if (ext === "jsx") return "jsx";
-	return ext.length > 0 ? ext : "text";
-}
-function stripBadges(text) {
-	return text.replace(/\[!\[[^\]]*]\([^)]+\)]\([^)]+\)/g, "").replace(/!\[[^\]]*]\([^)]+\)/g, "").replace(/<img[^>]*>/gi, "").replace(/<[^>]+>/g, "").replace(/\s+/g, " ").trim();
-}
-
 //#endregion
 //#region src/sources/collect.ts
 async function collectFacts(options) {
@@ -2534,13 +2596,15 @@ async function collectFacts(options) {
 	const remote = await collectGitRemote(options.cwd);
 	const changelog = await collectBestChangelog(options.cwd, version, options.changelogPath ?? "CHANGELOG.md", options.packagePath);
 	const readme = await collectReadme(options.cwd);
+	const snippet = options.snippet !== void 0 && options.snippet !== null && options.snippet.length > 0 ? await collectConfiguredSnippet(options.cwd, options.snippet) : {};
 	const parts = [
-		remote,
 		pkg,
+		pkg.project?.npmPackage === void 0 ? await collectWorkspaceNpmPackage(options.cwd, options.skipNetwork === true ? {} : { verify: async (name) => npmPackageExists(name, options.fetchImpl ?? fetch) }) : {},
+		remote,
 		git,
-		readme,
+		snippet,
 		changelog,
-		options.snippet !== void 0 && options.snippet !== null && options.snippet.length > 0 ? await collectConfiguredSnippet(options.cwd, options.snippet) : {}
+		readme
 	];
 	if (options.event.kind === "bench") parts.push(await collectBenchFile(options.cwd, options.benchFile ?? ".shipseal/bench.json"));
 	if (options.skipNetwork !== true) {
@@ -2581,6 +2645,31 @@ async function collectBestChangelog(cwd, version, changelogPath, packagePath) {
 	const candidates = await workspaceChangelogs(cwd);
 	return (await Promise.all(candidates.map((candidate) => collectChangelog(cwd, version, candidate)))).find((facts) => changelogHasNotes(facts)) ?? {};
 }
+/**
+* Find the one publishable package in a workspace.
+*
+* Only when there is exactly one candidate: two publishable packages make the CTA a guess, and
+* guessing which one to tell people to install is worse than falling back to the repository
+* URL. `--package` resolves the ambiguity explicitly.
+*/
+async function collectWorkspaceNpmPackage(cwd, options = {}) {
+	const paths = await workspaceManifests(cwd);
+	const found = (await Promise.all(paths.map((path) => collectPackageJson(cwd, path)))).map((facts, index) => ({
+		name: facts.project?.npmPackage?.value,
+		path: paths[index] ?? ""
+	})).filter((entry) => entry.name !== void 0);
+	const only = found.length === 1 ? found[0] : void 0;
+	if (only === void 0) return {};
+	if (options.verify !== void 0 && await options.verify(only.name) === false) return {};
+	return { project: { npmPackage: fact(only.name, {
+		source: "package-json",
+		ref: `${only.path}#name`,
+		fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+	}) } };
+}
+async function workspaceManifests(cwd) {
+	return (await workspaceChangelogs(cwd)).map((path) => path.replace(/CHANGELOG\.md$/, "package.json"));
+}
 async function workspaceChangelogs(cwd) {
 	return (await Promise.all(["packages", "apps"].map(async (root) => {
 		let entries;