Skip to content

Commit 1f91879

Browse files
murataslan1cursoragentAndarist
authored
Improve error messages for malformed changeset files (#1831)
* fix(parse): improve error messages for malformed changesets Fixes #175 This PR improves the error handling and messages when parsing malformed changeset files. The previous error messages were generic and didn't help users understand what went wrong. Changes: - Add validation for empty changeset files with helpful example - Improve error message when frontmatter is missing or invalid - Add specific error for invalid YAML in frontmatter, including the YAML error - Validate version types (major, minor, patch, none) with clear error message - Validate package names are non-empty strings - Include examples of correct format in error messages - Add tests for all new error scenarios The error messages now: - Explain what went wrong - Show what was received - Provide an example of the correct format Co-authored-by: Cursor <[email protected]> * chore: add changeset file Co-authored-by: Cursor <[email protected]> * chore: address review feedback * chore: address copilot feedback * revert yarn.lock changes * tweak * tweak * tweak * tweak --------- Co-authored-by: Murat Aslan <[email protected]> Co-authored-by: Cursor <[email protected]> Co-authored-by: Mateusz Burzyński <[email protected]>
1 parent 73b1809 commit 1f91879

4 files changed

Lines changed: 212 additions & 25 deletions

File tree

‎.changeset/improve-parse-errors.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@changesets/parse": patch
3+
---
4+
5+
Improve error messages for malformed changeset files. The new error messages explain what went wrong, show what was received, and provide examples of the correct format.

‎packages/parse/src/index.test.ts‎

Lines changed: 106 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,16 @@ describe("parsing a changeset", () => {
236236
`;
237237

238238
expect(() => parse(changesetMd)).toThrowErrorMatchingInlineSnapshot(`
239-
"could not parse changeset - invalid frontmatter: ---
239+
"could not parse changeset - missing or invalid frontmatter.
240+
Changesets must start with frontmatter delimited by "---".
241+
Example:
242+
---
243+
"package-name": patch
244+
---
245+
246+
Your changeset summary here.
247+
Received content:
248+
---
240249
"cool-package": minor
241250
--- fail
242251
@@ -253,8 +262,102 @@ describe("parsing a changeset", () => {
253262
`;
254263

255264
expect(() => parse(changesetMd)).toThrowErrorMatchingInlineSnapshot(`
256-
"could not parse changeset - invalid frontmatter: ---
257-
: minor
265+
"could not parse changeset - invalid YAML in frontmatter.
266+
The frontmatter between the "---" delimiters must be valid YAML.
267+
YAML error: incomplete explicit mapping pair; a key node is missed; or followed by a non-tabulated empty line (2:1)
268+
269+
1 |
270+
2 | : minor
271+
-----^
272+
Frontmatter content:
273+
274+
: minor"
275+
`);
276+
});
277+
278+
it("should throw when file is completely empty", () => {
279+
expect(() => parse("")).toThrowErrorMatchingInlineSnapshot(`
280+
"could not parse changeset - file is empty.
281+
Changesets must have frontmatter with package names and version types.
282+
Example:
283+
---
284+
"package-name": patch
285+
---
286+
287+
Your changeset summary here."
288+
`);
289+
expect(() => parse(" ")).toThrowErrorMatchingInlineSnapshot(`
290+
"could not parse changeset - file is empty.
291+
Changesets must have frontmatter with package names and version types.
292+
Example:
293+
---
294+
"package-name": patch
295+
---
296+
297+
Your changeset summary here."
298+
`);
299+
expect(() => parse("\n\n")).toThrowErrorMatchingInlineSnapshot(`
300+
"could not parse changeset - file is empty.
301+
Changesets must have frontmatter with package names and version types.
302+
Example:
303+
---
304+
"package-name": patch
305+
---
306+
307+
Your changeset summary here."
308+
`);
309+
});
310+
311+
it("should throw when frontmatter is missing", () => {
312+
const changesetMd = "Just some content without frontmatter";
313+
expect(() => parse(changesetMd)).toThrowErrorMatchingInlineSnapshot(`
314+
"could not parse changeset - missing or invalid frontmatter.
315+
Changesets must start with frontmatter delimited by "---".
316+
Example:
317+
---
318+
"package-name": patch
319+
---
320+
321+
Your changeset summary here.
322+
Received content:
323+
Just some content without frontmatter"
324+
`);
325+
});
326+
327+
it("should throw when version type is invalid", () => {
328+
const changesetMd = outdent`---
329+
"cool-package": invalid-type
330+
---
331+
332+
Nice simple summary
333+
`;
334+
335+
expect(() => parse(changesetMd)).toThrowErrorMatchingInlineSnapshot(`
336+
"could not parse changeset - invalid version type "invalid-type" for package "cool-package".
337+
Valid version types are: major, minor, patch, none
338+
Changeset contents:
339+
---
340+
"cool-package": invalid-type
341+
---
342+
343+
Nice simple summary"
344+
`);
345+
});
346+
347+
it("should throw with helpful message when package name is empty", () => {
348+
const changesetMd = outdent`---
349+
"": minor
350+
---
351+
352+
Nice simple summary
353+
`;
354+
355+
expect(() => parse(changesetMd)).toThrowErrorMatchingInlineSnapshot(`
356+
"could not parse changeset - invalid package name in frontmatter.
357+
Expected a non-empty string for package name, but got: ""
358+
Changeset contents:
359+
---
360+
"": minor
258361
---
259362
260363
Nice simple summary"

‎packages/parse/src/index.ts‎

Lines changed: 82 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,42 +3,108 @@ import { Release, VersionType } from "@changesets/types";
33

44
const mdRegex = /\s*---([^]*?)\n\s*---(\s*(?:\n|$)[^]*)/;
55

6+
const EXAMPLE_FORMAT = `---\n"package-name": patch\n---`;
7+
8+
const validVersionTypes: readonly VersionType[] = [
9+
"major",
10+
"minor",
11+
"patch",
12+
"none",
13+
];
14+
15+
function truncate(s: string, max = 200): string {
16+
return s.length > max ? s.slice(0, max) + "..." : s;
17+
}
18+
19+
function validateReleases(releases: Release[], contents: string): void {
20+
for (const release of releases) {
21+
if (typeof release.name !== "string" || release.name.trim() === "") {
22+
throw new Error(
23+
`could not parse changeset - invalid package name in frontmatter.\n` +
24+
`Expected a non-empty string for package name, but got: ${JSON.stringify(
25+
release.name
26+
)}\n` +
27+
`Changeset contents:\n${truncate(contents)}`
28+
);
29+
}
30+
31+
if (typeof release.type !== "string") {
32+
throw new Error(
33+
`could not parse changeset - invalid release type for package "${release.name}".\n` +
34+
`Expected a string for release type, but got: ${typeof release.type}\n` +
35+
`Changeset contents:\n${truncate(contents)}`
36+
);
37+
}
38+
39+
if (!validVersionTypes.includes(release.type)) {
40+
throw new Error(
41+
`could not parse changeset - invalid version type ${JSON.stringify(
42+
release.type
43+
)} for package "${release.name}".\n` +
44+
`Valid version types are: ${validVersionTypes.join(", ")}\n` +
45+
`Changeset contents:\n${truncate(contents)}`
46+
);
47+
}
48+
}
49+
}
50+
651
export default function parseChangesetFile(contents: string): {
752
summary: string;
853
releases: Release[];
954
} {
55+
const trimmedContents = contents.trim();
56+
57+
if (!trimmedContents) {
58+
throw new Error(
59+
`could not parse changeset - file is empty.\n` +
60+
`Changesets must have frontmatter with package names and version types.\n` +
61+
`Example:\n${EXAMPLE_FORMAT}\n\nYour changeset summary here.`
62+
);
63+
}
64+
1065
const execResult = mdRegex.exec(contents);
1166
if (!execResult) {
1267
throw new Error(
13-
`could not parse changeset - invalid frontmatter: ${contents}`
68+
`could not parse changeset - missing or invalid frontmatter.\n` +
69+
`Changesets must start with frontmatter delimited by "---".\n` +
70+
`Example:\n${EXAMPLE_FORMAT}\n\nYour changeset summary here.\n` +
71+
`Received content:\n${truncate(trimmedContents)}`
1472
);
1573
}
1674
let [, roughReleases, roughSummary] = execResult;
1775
let summary = roughSummary.trim();
1876

1977
let releases: Release[];
78+
let yamlStuff: Record<string, VersionType> | undefined;
2079
try {
21-
const yamlStuff = yaml.load(roughReleases) as
22-
| Record<string, VersionType>
23-
| undefined;
24-
25-
if (yamlStuff) {
26-
releases = Object.entries(yamlStuff).map(([name, type]) => ({
27-
name,
28-
type,
29-
}));
30-
} else {
31-
releases = [];
32-
}
80+
yamlStuff = yaml.load(roughReleases) as typeof yamlStuff;
3381
} catch (e) {
3482
throw new Error(
35-
`could not parse changeset - invalid frontmatter: ${contents}`
83+
`could not parse changeset - invalid YAML in frontmatter.\n` +
84+
`The frontmatter between the "---" delimiters must be valid YAML.\n` +
85+
`YAML error: ${e instanceof Error ? e.message : String(e)}\n` +
86+
`Frontmatter content:\n${roughReleases}`
3687
);
3788
}
3889

39-
if (!releases) {
40-
throw new Error(`could not parse changeset - unknown error: ${contents}`);
90+
if (yamlStuff) {
91+
if (typeof yamlStuff !== "object" || Array.isArray(yamlStuff)) {
92+
throw new Error(
93+
`could not parse changeset - frontmatter must be an object mapping package names to version types.\n` +
94+
`Expected format:\n${EXAMPLE_FORMAT}\n` +
95+
`Received:\n${roughReleases}`
96+
);
97+
}
98+
99+
releases = Object.entries(yamlStuff).map(([name, type]) => ({
100+
name,
101+
type,
102+
}));
103+
} else {
104+
releases = [];
41105
}
42106

107+
validateReleases(releases, contents);
108+
43109
return { releases, summary };
44110
}

‎packages/read/src/index.test.ts‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
import fs from "fs-extra";
22
import path from "node:path";
3-
import outdent from "outdent";
43

54
import read from "./";
65
import { gitdir, silenceLogsInBlock, testdir } from "@changesets/test-utils";
@@ -98,13 +97,15 @@ I'm amazed we needed to update the best package, because it was already the best
9897
},
9998
]);
10099
});
100+
101101
it("should return an empty array when no changesets are found", async () => {
102102
const cwd = await testdir({});
103103
await fs.mkdir(path.join(cwd, ".changeset"));
104104

105105
const changesets = await read(cwd);
106106
expect(changesets).toEqual([]);
107107
});
108+
108109
it("should error when there is no changeset folder", async () => {
109110
const cwd = await testdir({});
110111

@@ -118,7 +119,8 @@ I'm amazed we needed to update the best package, because it was already the best
118119
}
119120
expect("never run this because we returned above").toBe(true);
120121
});
121-
it("should error on broken changeset?", async () => {
122+
123+
it("should error on broken changeset", async () => {
122124
const cwd = await testdir({
123125
".changeset/broken-changeset.md": `---
124126
@@ -129,16 +131,26 @@ I'm amazed we needed to update the best package, because it was already the best
129131
Everything is wrong`,
130132
});
131133

132-
expect(read(cwd)).rejects.toThrow(
133-
outdent`could not parse changeset - invalid frontmatter: ---
134+
await expect(read(cwd)).rejects.toThrowErrorMatchingInlineSnapshot(`
135+
"could not parse changeset - missing or invalid frontmatter.
136+
Changesets must start with frontmatter delimited by "---".
137+
Example:
138+
---
139+
"package-name": patch
140+
---
141+
142+
Your changeset summary here.
143+
Received content:
144+
---
134145
135146
"cool-package": minor
136147
137148
--
138149
139-
Everything is wrong`
140-
);
150+
Everything is wrong"
151+
`);
141152
});
153+
142154
it("should return no releases and empty summary when the changeset is empty", async () => {
143155
const cwd = await testdir({
144156
".changeset/empty-like-void.md": `---
@@ -154,6 +166,7 @@ Everything is wrong`,
154166
},
155167
]);
156168
});
169+
157170
it("should filter out ignored changesets", async () => {
158171
const cwd = await testdir({
159172
"package.json": JSON.stringify({

0 commit comments

Comments
 (0)