@effected/changesets 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Changelog.js +414 -0
- package/ChangesetConfig.js +71 -13
- package/ChangesetFile.js +2 -2
- package/ChangesetLint.js +142 -77
- package/PendingChangesets.js +120 -29
- package/README.md +27 -13
- package/ReleaseEdits.js +226 -0
- package/ReleasePlan.js +345 -96
- package/errors.js +56 -1
- package/index.d.ts +922 -59
- package/index.js +5 -3
- package/internal/causeMessage.js +57 -0
- package/internal/frontMatter.js +83 -0
- package/internal/versions.js +103 -0
- package/lint.d.ts +71 -65
- package/package.json +4 -4
- package/internal/lint/content-structure.js +0 -37
- package/internal/lint/dependency-table-format.js +0 -117
- package/internal/lint/docs.js +0 -72
- package/internal/lint/heading-hierarchy.js +0 -32
- package/internal/lint/required-sections.js +0 -23
- package/internal/lint/uncategorized-content.js +0 -22
package/ChangesetLint.js
CHANGED
|
@@ -1,62 +1,106 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import { HeadingHierarchy } from "./internal/lint/heading-hierarchy.js";
|
|
4
|
-
import { RequiredSections } from "./internal/lint/required-sections.js";
|
|
5
|
-
import { UncategorizedContent } from "./internal/lint/uncategorized-content.js";
|
|
6
|
-
import { MarkdownLint } from "@effected/markdown-lint";
|
|
1
|
+
import { readFrontMatter } from "./internal/frontMatter.js";
|
|
2
|
+
import { LintRule, MarkdownLint } from "@effected/markdown-lint";
|
|
7
3
|
|
|
8
4
|
// src/ChangesetLint.ts
|
|
5
|
+
const RELEASE_TYPES = /* @__PURE__ */ new Set([
|
|
6
|
+
"major",
|
|
7
|
+
"minor",
|
|
8
|
+
"patch",
|
|
9
|
+
"none"
|
|
10
|
+
]);
|
|
11
|
+
const TAGS = ["changeset", "front-matter"];
|
|
9
12
|
/**
|
|
10
|
-
*
|
|
11
|
-
* `
|
|
12
|
-
|
|
13
|
-
|
|
13
|
+
* A front matter value as a diagnostic quotes it. Never throws: YAML decodes an integer past 2^53 as a bigint, which
|
|
14
|
+
* `JSON.stringify` refuses, at the top level or nested, so a rule reports the value instead of crashing on it.
|
|
15
|
+
*/
|
|
16
|
+
const showValue = (value) => {
|
|
17
|
+
if (typeof value === "bigint") return String(value);
|
|
18
|
+
try {
|
|
19
|
+
return JSON.stringify(value, (_key, v) => typeof v === "bigint" ? String(v) : v) ?? String(value);
|
|
20
|
+
} catch {
|
|
21
|
+
return Object.prototype.toString.call(value);
|
|
22
|
+
}
|
|
23
|
+
};
|
|
24
|
+
/** The entries of a front matter `@changesets/parse` accepts; none when it refuses one, which `frontMatter` reports. */
|
|
25
|
+
const entriesOf = (context) => {
|
|
26
|
+
const read = readFrontMatter(context.source);
|
|
27
|
+
return read.ok ? read.entries : [];
|
|
28
|
+
};
|
|
29
|
+
const frontMatter = LintRule.make({
|
|
30
|
+
names: ["changeset-front-matter", "CF001"],
|
|
31
|
+
description: "A changeset starts with a front matter block of YAML mapping package names to release types",
|
|
32
|
+
tags: [...TAGS],
|
|
33
|
+
check: (context, report) => {
|
|
34
|
+
const read = readFrontMatter(context.source);
|
|
35
|
+
if (!read.ok) report(context.diagnostic({
|
|
36
|
+
at: read.at,
|
|
37
|
+
detail: read.detail
|
|
38
|
+
}));
|
|
39
|
+
}
|
|
40
|
+
});
|
|
41
|
+
const packageName = LintRule.make({
|
|
42
|
+
names: ["changeset-package-name", "CF002"],
|
|
43
|
+
description: "Every front matter key names a package",
|
|
44
|
+
tags: [...TAGS],
|
|
45
|
+
check: (context, report) => {
|
|
46
|
+
for (const entry of entriesOf(context)) {
|
|
47
|
+
if (entry.name.trim() !== "") continue;
|
|
48
|
+
report(context.diagnostic({
|
|
49
|
+
at: entry.at,
|
|
50
|
+
detail: `${JSON.stringify(entry.name)} is not a package name: a key must name a package.`
|
|
51
|
+
}));
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
const releaseType = LintRule.make({
|
|
56
|
+
names: ["changeset-release-type", "CF003"],
|
|
57
|
+
description: "Every front matter value is major, minor, patch or none",
|
|
58
|
+
tags: [...TAGS],
|
|
59
|
+
check: (context, report) => {
|
|
60
|
+
for (const entry of entriesOf(context)) {
|
|
61
|
+
if (RELEASE_TYPES.has(entry.type)) continue;
|
|
62
|
+
report(context.diagnostic({
|
|
63
|
+
at: entry.at,
|
|
64
|
+
detail: `${entry.name}: ${showValue(entry.type)} is not a release type; use major, minor, patch or none.`,
|
|
65
|
+
context: entry.name
|
|
66
|
+
}));
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
});
|
|
70
|
+
/**
|
|
71
|
+
* Lint rules for changeset files that hold under any house style: only what
|
|
72
|
+
* the changesets tool itself refuses a file for, as `@changesets/parse`
|
|
73
|
+
* reads one, plus, when the workspace's names are given, that each named
|
|
74
|
+
* package exists.
|
|
14
75
|
*
|
|
15
76
|
* @remarks
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
* -
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
* thirteen categories (`Breaking Changes`, `Features`, `Bug Fixes`,
|
|
22
|
-
* `Performance`, `Documentation`, `Refactoring`, `Tests`, `Build System`,
|
|
23
|
-
* `CI`, `Dependencies`, `Maintenance`, `Reverts`, `Other`), ignoring case.
|
|
24
|
-
* - `CSH003` `changeset-content-structure`: no empty section, no code fence
|
|
25
|
-
* without a language, no empty list item.
|
|
26
|
-
* - `CSH004` `changeset-uncategorized-content`: no content before the first
|
|
27
|
-
* `h2`.
|
|
28
|
-
* - `CSH005` `changeset-dependency-table-format`: a `Dependencies` section
|
|
29
|
-
* holds a `Dependency | Type | Action | From | To` table whose cells are
|
|
30
|
-
* valid.
|
|
77
|
+
* Each rule is an `@effected/markdown-lint` `LintRule`, so one definition
|
|
78
|
+
* runs in `MarkdownLint` and, through `MarkdownlintAdapter`, in markdownlint
|
|
79
|
+
* and markdownlint-cli2. A house style (section headings, summary layout)
|
|
80
|
+
* is not here: pass its rules as `rules`, or beside these to
|
|
81
|
+
* `MarkdownlintAdapter.rules`.
|
|
31
82
|
*
|
|
32
|
-
*
|
|
33
|
-
* rules. systems implements each rule twice, and where its two engines
|
|
34
|
-
* disagree these follow its markdownlint engine, the one markdownlint-cli2
|
|
35
|
-
* and a pre-commit hook run. That engine reads micromark tokens, so:
|
|
83
|
+
* The rules, named in their own scheme: `CF` for changeset front matter.
|
|
36
84
|
*
|
|
37
|
-
* -
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
* `
|
|
44
|
-
*
|
|
45
|
-
* -
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
* pads it with empty cells, which are not counted.
|
|
51
|
-
* - A setext heading directly under a link reference definition is
|
|
52
|
-
* reported on the definition's line, where micromark starts its token.
|
|
53
|
-
* - A heading over several lines is named on one line, as markdownlint
|
|
54
|
-
* writes every detail.
|
|
85
|
+
* - `CF001` `changeset-front-matter`: the file is not empty, has a front
|
|
86
|
+
* matter block between `---` lines, the block is YAML, and a non-empty
|
|
87
|
+
* value is a mapping. The block is found with `@changesets/parse`'s own
|
|
88
|
+
* pattern, which allows leading whitespace and does not require the block
|
|
89
|
+
* at the start of the file.
|
|
90
|
+
* - `CF002` `changeset-package-name`: every key is a package name, which
|
|
91
|
+
* `@changesets/parse` checks only as not blank, and neither does this: an
|
|
92
|
+
* npm-name check would refuse files changesets accepts.
|
|
93
|
+
* - `CF003` `changeset-release-type`: every value is `major`, `minor`,
|
|
94
|
+
* `patch` or `none`.
|
|
95
|
+
* - `CF004` `changeset-known-package`, from
|
|
96
|
+
* {@link ChangesetLint.knownPackages}: every key names a package of the
|
|
97
|
+
* workspace. It runs only when the names are given.
|
|
55
98
|
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
99
|
+
* An empty front matter and an empty summary are both legal: they are what
|
|
100
|
+
* `changeset add --empty` writes. `CF002` to `CF004` read only a front
|
|
101
|
+
* matter `CF001` accepts, so a broken block is reported once.
|
|
102
|
+
* `__test__/ChangesetLint.test.ts` holds the defaults to `@changesets/parse`:
|
|
103
|
+
* a file it parses fails none of them, and a file it refuses fails one.
|
|
60
104
|
*
|
|
61
105
|
* @example
|
|
62
106
|
* ```ts
|
|
@@ -64,44 +108,65 @@ import { MarkdownLint } from "@effected/markdown-lint";
|
|
|
64
108
|
* import { ChangesetLint } from "@effected/changesets/lint";
|
|
65
109
|
*
|
|
66
110
|
* // .markdownlint-cli2.mjs
|
|
67
|
-
* export default { customRules: MarkdownlintAdapter.rules(ChangesetLint.
|
|
111
|
+
* export default { customRules: MarkdownlintAdapter.rules(ChangesetLint.defaults) };
|
|
68
112
|
* ```
|
|
69
113
|
*
|
|
70
114
|
* @public
|
|
71
115
|
*/
|
|
72
116
|
var ChangesetLint = class ChangesetLint {
|
|
73
|
-
/**
|
|
74
|
-
static
|
|
75
|
-
/**
|
|
76
|
-
static
|
|
77
|
-
/**
|
|
78
|
-
static
|
|
79
|
-
/**
|
|
80
|
-
static
|
|
81
|
-
|
|
82
|
-
|
|
117
|
+
/** `CF001`: a front matter block of YAML, a mapping when not empty. */
|
|
118
|
+
static frontMatter = frontMatter;
|
|
119
|
+
/** `CF002`: every key names a package. */
|
|
120
|
+
static packageName = packageName;
|
|
121
|
+
/** `CF003`: every value is a release type. */
|
|
122
|
+
static releaseType = releaseType;
|
|
123
|
+
/** The default rules, `CF001` to `CF003`, in that order. */
|
|
124
|
+
static defaults = [
|
|
125
|
+
frontMatter,
|
|
126
|
+
packageName,
|
|
127
|
+
releaseType
|
|
128
|
+
];
|
|
83
129
|
/**
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
130
|
+
* `CF004` `changeset-known-package`: every front matter key names one of
|
|
131
|
+
* `packages`, the workspace's package names.
|
|
132
|
+
*
|
|
133
|
+
* @param packages - The workspace's package names.
|
|
87
134
|
*/
|
|
88
|
-
static
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
135
|
+
static knownPackages(packages) {
|
|
136
|
+
const known = new Set(packages);
|
|
137
|
+
return LintRule.make({
|
|
138
|
+
names: ["changeset-known-package", "CF004"],
|
|
139
|
+
description: "Every front matter key names a package of the workspace",
|
|
140
|
+
tags: [...TAGS],
|
|
141
|
+
check: (context, report) => {
|
|
142
|
+
for (const entry of entriesOf(context)) {
|
|
143
|
+
if (entry.name.trim() === "" || known.has(entry.name)) continue;
|
|
144
|
+
report(context.diagnostic({
|
|
145
|
+
at: entry.at,
|
|
146
|
+
detail: `${entry.name} is not a package of this workspace.`,
|
|
147
|
+
context: entry.name
|
|
148
|
+
}));
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
});
|
|
152
|
+
}
|
|
95
153
|
/**
|
|
96
|
-
* Lint one changeset file's text
|
|
97
|
-
*
|
|
98
|
-
*
|
|
154
|
+
* Lint one changeset file's text: `MarkdownLint.lint` over
|
|
155
|
+
* {@link ChangesetLint.defaults} (or `options.defaults`), then
|
|
156
|
+
* {@link ChangesetLint.knownPackages} when `options.packages` is given,
|
|
157
|
+
* then `options.rules`. Line numbers count the whole file, front matter
|
|
158
|
+
* included.
|
|
99
159
|
*
|
|
100
160
|
* @param source - The changeset file's text.
|
|
101
|
-
* @param options -
|
|
161
|
+
* @param options - The rules and the parse options.
|
|
102
162
|
*/
|
|
103
163
|
static lint(source, options) {
|
|
104
|
-
|
|
164
|
+
const { packages, rules, defaults, ...parse } = options ?? {};
|
|
165
|
+
return MarkdownLint.lint(source, [
|
|
166
|
+
...defaults ?? ChangesetLint.defaults,
|
|
167
|
+
...packages === void 0 ? [] : [ChangesetLint.knownPackages(packages)],
|
|
168
|
+
...rules ?? []
|
|
169
|
+
], parse);
|
|
105
170
|
}
|
|
106
171
|
};
|
|
107
172
|
|
package/PendingChangesets.js
CHANGED
|
@@ -18,9 +18,18 @@ var PendingChangeset = class extends Schema.Class("PendingChangeset")({
|
|
|
18
18
|
file: Schema.String,
|
|
19
19
|
/** Package name to requested release type, in file order. */
|
|
20
20
|
releases: Schema.ReadonlyMap(Schema.String, ReleaseType),
|
|
21
|
-
/** The markdown after the front matter. */
|
|
21
|
+
/** The markdown after the front matter, trimmed as `@changesets/parse` trims it. */
|
|
22
22
|
summary: Schema.String
|
|
23
|
-
}) {
|
|
23
|
+
}) {
|
|
24
|
+
/**
|
|
25
|
+
* The changeset's id, as `@changesets/read` gives it: `file` without
|
|
26
|
+
* `.md`, so `pre/<name>` for one an earlier pre-release consumed. A
|
|
27
|
+
* `PlannedRelease`'s `changesets` lists these.
|
|
28
|
+
*/
|
|
29
|
+
get id() {
|
|
30
|
+
return this.file.replace(/\.md$/, "");
|
|
31
|
+
}
|
|
32
|
+
};
|
|
24
33
|
/** The directory, under `.changeset/`, holding the changesets a pre-release consumed. */
|
|
25
34
|
const PRE = "pre";
|
|
26
35
|
const CONTEXT_FILES = /* @__PURE__ */ new Set([
|
|
@@ -61,6 +70,47 @@ const toPlatformError = (method, path, cause) => PlatformError.systemError({
|
|
|
61
70
|
cause
|
|
62
71
|
});
|
|
63
72
|
const isNotFound = (error) => error.reason._tag === "NotFound";
|
|
73
|
+
/** The changeset files under `.changeset/`, then those under `.changeset/pre/` as `pre/<name>.md`. */
|
|
74
|
+
const listFiles = Effect.fnUntraced(function* (dir) {
|
|
75
|
+
const fs = yield* FileSystem.FileSystem;
|
|
76
|
+
const path = yield* Path.Path;
|
|
77
|
+
const list = (directory) => fs.readDirectory(directory).pipe(Effect.catch((error) => isNotFound(error) ? Effect.succeed([]) : Effect.fail(error)));
|
|
78
|
+
const names = selectNames(yield* list(dir));
|
|
79
|
+
const consumed = selectNames(yield* list(path.join(dir, PRE)));
|
|
80
|
+
return [...names, ...consumed.map((name) => `${PRE}/${name}`)];
|
|
81
|
+
});
|
|
82
|
+
/** {@link listFiles} over `node:fs`; `dir` is the `.changeset` directory with no trailing separator. */
|
|
83
|
+
const listFilesSync = (dir) => {
|
|
84
|
+
const list = (directory) => {
|
|
85
|
+
try {
|
|
86
|
+
return Result.succeed(selectNames(readdirSync(directory)));
|
|
87
|
+
} catch (cause) {
|
|
88
|
+
const error = toPlatformError("readDirectory", directory, cause);
|
|
89
|
+
return isNotFound(error) ? Result.succeed([]) : Result.fail(error);
|
|
90
|
+
}
|
|
91
|
+
};
|
|
92
|
+
const names = list(dir);
|
|
93
|
+
if (Result.isFailure(names)) return Result.fail(names.failure);
|
|
94
|
+
const consumed = list(`${dir}/${PRE}`);
|
|
95
|
+
if (Result.isFailure(consumed)) return Result.fail(consumed.failure);
|
|
96
|
+
return Result.succeed([...names.success, ...consumed.success.map((name) => `${PRE}/${name}`)]);
|
|
97
|
+
};
|
|
98
|
+
/** `<root>/.changeset`, trimming any run of trailing separators off `root`. */
|
|
99
|
+
const changesetDirSync = (root) => {
|
|
100
|
+
let end = root.length;
|
|
101
|
+
while (end > 0 && (root[end - 1] === "/" || root[end - 1] === "\\")) end--;
|
|
102
|
+
return `${root.slice(0, end)}/.changeset`;
|
|
103
|
+
};
|
|
104
|
+
/** Read and parse one changeset file over `node:fs`. */
|
|
105
|
+
const readOneSync = (dir, file) => {
|
|
106
|
+
let text;
|
|
107
|
+
try {
|
|
108
|
+
text = readFileSync(`${dir}/${file}`, "utf8");
|
|
109
|
+
} catch (cause) {
|
|
110
|
+
return Result.fail(toPlatformError("readFile", `${dir}/${file}`, cause));
|
|
111
|
+
}
|
|
112
|
+
return toPending(file, text);
|
|
113
|
+
};
|
|
64
114
|
/**
|
|
65
115
|
* Reading the pending changesets under a repository's `.changeset/`
|
|
66
116
|
* directory.
|
|
@@ -75,54 +125,95 @@ var PendingChangesets = class {
|
|
|
75
125
|
* `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, dotfiles and non-`.md` files are
|
|
76
126
|
* skipped; a missing directory answers `[]`.
|
|
77
127
|
*
|
|
128
|
+
* The read is all or nothing: the first file that does not read or parse
|
|
129
|
+
* fails it. {@link PendingChangesets.readSettled} reads the same files and
|
|
130
|
+
* skips a bad one instead.
|
|
131
|
+
*
|
|
78
132
|
* @param root - The repository root.
|
|
79
133
|
*/
|
|
80
134
|
static read = Effect.fn("PendingChangesets.read")(function* (root) {
|
|
81
135
|
const fs = yield* FileSystem.FileSystem;
|
|
82
136
|
const path = yield* Path.Path;
|
|
83
137
|
const dir = path.join(root, ".changeset");
|
|
84
|
-
const
|
|
85
|
-
const names = selectNames(yield* list(dir));
|
|
86
|
-
const consumed = selectNames(yield* list(path.join(dir, PRE)));
|
|
87
|
-
const files = [...names, ...consumed.map((name) => `${PRE}/${name}`)];
|
|
138
|
+
const files = yield* listFiles(dir);
|
|
88
139
|
return yield* Effect.forEach(files, (file) => fs.readFileString(path.join(dir, file)).pipe(Effect.flatMap((text) => Effect.fromResult(toPending(file, text)))));
|
|
89
140
|
});
|
|
90
141
|
/**
|
|
142
|
+
* Read the same files as {@link PendingChangesets.read}, in the same order,
|
|
143
|
+
* but skip a file that does not read or parse and report it in `failures`
|
|
144
|
+
* rather than failing the whole read. For a best-effort view of pending
|
|
145
|
+
* bumps; a versioning tool wants the strict {@link PendingChangesets.read}.
|
|
146
|
+
*
|
|
147
|
+
* Listing `.changeset/` or `.changeset/pre/` still fails the effect with a
|
|
148
|
+
* `PlatformError`, since then no file is known to be missing; a missing
|
|
149
|
+
* directory answers no changesets and no failures.
|
|
150
|
+
*
|
|
151
|
+
* @param root - The repository root.
|
|
152
|
+
*/
|
|
153
|
+
static readSettled = Effect.fn("PendingChangesets.readSettled")(function* (root) {
|
|
154
|
+
const fs = yield* FileSystem.FileSystem;
|
|
155
|
+
const path = yield* Path.Path;
|
|
156
|
+
const dir = path.join(root, ".changeset");
|
|
157
|
+
const files = yield* listFiles(dir);
|
|
158
|
+
const changesets = [];
|
|
159
|
+
const failures = [];
|
|
160
|
+
for (const file of files) {
|
|
161
|
+
const result = yield* fs.readFileString(path.join(dir, file)).pipe(Effect.flatMap((text) => Effect.fromResult(toPending(file, text))), Effect.result);
|
|
162
|
+
if (Result.isSuccess(result)) changesets.push(result.success);
|
|
163
|
+
else failures.push({
|
|
164
|
+
file,
|
|
165
|
+
error: result.failure
|
|
166
|
+
});
|
|
167
|
+
}
|
|
168
|
+
return {
|
|
169
|
+
changesets,
|
|
170
|
+
failures
|
|
171
|
+
};
|
|
172
|
+
});
|
|
173
|
+
/**
|
|
91
174
|
* Synchronous {@link PendingChangesets.read} over `node:fs`, for callers
|
|
92
175
|
* that run before any Effect runtime exists.
|
|
93
176
|
*
|
|
94
177
|
* @param root - The repository root.
|
|
95
178
|
*/
|
|
96
179
|
static readSync(root) {
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
const list = (directory) => {
|
|
101
|
-
try {
|
|
102
|
-
return Result.succeed(selectNames(readdirSync(directory)));
|
|
103
|
-
} catch (cause) {
|
|
104
|
-
const error = toPlatformError("readDirectory", directory, cause);
|
|
105
|
-
return isNotFound(error) ? Result.succeed([]) : Result.fail(error);
|
|
106
|
-
}
|
|
107
|
-
};
|
|
108
|
-
const names = list(dir);
|
|
109
|
-
if (Result.isFailure(names)) return Result.fail(names.failure);
|
|
110
|
-
const consumed = list(`${dir}/${PRE}`);
|
|
111
|
-
if (Result.isFailure(consumed)) return Result.fail(consumed.failure);
|
|
180
|
+
const dir = changesetDirSync(root);
|
|
181
|
+
const files = listFilesSync(dir);
|
|
182
|
+
if (Result.isFailure(files)) return Result.fail(files.failure);
|
|
112
183
|
const pending = [];
|
|
113
|
-
for (const file of
|
|
114
|
-
|
|
115
|
-
try {
|
|
116
|
-
text = readFileSync(`${dir}/${file}`, "utf8");
|
|
117
|
-
} catch (cause) {
|
|
118
|
-
return Result.fail(toPlatformError("readFile", `${dir}/${file}`, cause));
|
|
119
|
-
}
|
|
120
|
-
const parsed = toPending(file, text);
|
|
184
|
+
for (const file of files.success) {
|
|
185
|
+
const parsed = readOneSync(dir, file);
|
|
121
186
|
if (Result.isFailure(parsed)) return Result.fail(parsed.failure);
|
|
122
187
|
pending.push(parsed.success);
|
|
123
188
|
}
|
|
124
189
|
return Result.succeed(pending);
|
|
125
190
|
}
|
|
191
|
+
/**
|
|
192
|
+
* Synchronous {@link PendingChangesets.readSettled} over `node:fs`, for
|
|
193
|
+
* callers that run before any Effect runtime exists. Fails only when a
|
|
194
|
+
* directory cannot be listed.
|
|
195
|
+
*
|
|
196
|
+
* @param root - The repository root.
|
|
197
|
+
*/
|
|
198
|
+
static readSettledSync(root) {
|
|
199
|
+
const dir = changesetDirSync(root);
|
|
200
|
+
const files = listFilesSync(dir);
|
|
201
|
+
if (Result.isFailure(files)) return Result.fail(files.failure);
|
|
202
|
+
const changesets = [];
|
|
203
|
+
const failures = [];
|
|
204
|
+
for (const file of files.success) {
|
|
205
|
+
const parsed = readOneSync(dir, file);
|
|
206
|
+
if (Result.isSuccess(parsed)) changesets.push(parsed.success);
|
|
207
|
+
else failures.push({
|
|
208
|
+
file,
|
|
209
|
+
error: parsed.failure
|
|
210
|
+
});
|
|
211
|
+
}
|
|
212
|
+
return Result.succeed({
|
|
213
|
+
changesets,
|
|
214
|
+
failures
|
|
215
|
+
});
|
|
216
|
+
}
|
|
126
217
|
};
|
|
127
218
|
|
|
128
219
|
export { PendingChangeset, PendingChangesets };
|
package/README.md
CHANGED
|
@@ -23,9 +23,9 @@ Changeset files, `.changeset/config.json` and the release plan as Effect schemas
|
|
|
23
23
|
|
|
24
24
|
Tools that need to know the next versions usually shell out to `changeset status --output`, or carry `@changesets/get-release-plan` at runtime. This package answers the same question as typed values: every failure is a tagged error, and the planner is a pure function you can call with packages you already have.
|
|
25
25
|
|
|
26
|
-
It reads and
|
|
26
|
+
It reads, plans and computes; it never writes. What `changeset version` would write (each manifest's new version and ranges, the changesets it consumes, the `pre.json` it leaves, the CHANGELOG text) comes back as data, and your program does the IO. Nothing here publishes.
|
|
27
27
|
|
|
28
|
-
The answers are held to the original. `@changesets/get-release-plan`
|
|
28
|
+
The answers are held to the original. `@changesets/get-release-plan`, `@changesets/assemble-release-plan`, `@changesets/apply-release-plan` and `@changesets/changelog-git` are test-only dependencies, and the test suite requires the same answer from both over a set of small pnpm workspaces, down to the files `changeset version` writes. The cases where this package deliberately differs are listed under [Differences from changesets](#differences-from-changesets).
|
|
29
29
|
|
|
30
30
|
## Install
|
|
31
31
|
|
|
@@ -39,7 +39,7 @@ pnpm add @effected/changesets effect
|
|
|
39
39
|
|
|
40
40
|
Requires Node.js >=24.11.0. `effect` v4 is a peer dependency.
|
|
41
41
|
|
|
42
|
-
The changeset lint rules ship from `@effected/changesets/lint`, which also needs `@effected/markdown` and `@effected/markdown-lint`. Both are optional peers: install them only if you import that entry point. The root entry never loads them.
|
|
42
|
+
The changeset front-matter lint rules ship from `@effected/changesets/lint`, which also needs `@effected/markdown` and `@effected/markdown-lint`. Both are optional peers: install them only if you import that entry point. The root entry never loads them.
|
|
43
43
|
|
|
44
44
|
```bash
|
|
45
45
|
pnpm add @effected/markdown @effected/markdown-lint
|
|
@@ -52,7 +52,8 @@ All `@effected/*` packages are ESM-only: the exports maps publish only `import`
|
|
|
52
52
|
`ReleasePlan.read` discovers the workspace's packages, reads the config and the pending changesets, and plans the release. It requires `FileSystem`, `Path` and `WorkspaceDiscovery`, which you provide at the edge of your program:
|
|
53
53
|
|
|
54
54
|
```ts
|
|
55
|
-
import
|
|
55
|
+
import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
|
|
56
|
+
import * as NodePath from "@effect/platform-node/NodePath";
|
|
56
57
|
import { ReleasePlan } from "@effected/changesets";
|
|
57
58
|
import { WorkspaceDiscovery, WorkspaceRoot } from "@effected/workspaces";
|
|
58
59
|
import { Effect, Layer } from "effect";
|
|
@@ -76,16 +77,24 @@ Effect.runPromise(program);
|
|
|
76
77
|
|
|
77
78
|
A `none` entry is a package listed in the plan whose version does not move. Skip it if you only want what publishes. `plan.changesets` holds the changesets the plan was made from, and `plan.preState` the pre-release state, when there is one.
|
|
78
79
|
|
|
80
|
+
## Apply a release
|
|
81
|
+
|
|
82
|
+
`ReleasePlan.edits(plan, { packages, config })` returns what `changeset version` writes, as a `Result`: each `package.json`'s new `version` and rewritten ranges, the changesets to delete (or, in pre mode, to move under `.changeset/pre/`), and the `pre.json` the release leaves. Pass every package `WorkspaceDiscovery.listPackagesIn` lists, the root included.
|
|
83
|
+
|
|
84
|
+
`Changelog.entry(plan, release, functions, { packages, config })` renders a release's CHANGELOG block from a changelog module you load yourself, and `Changelog.insert(existing, block, name)` puts it in the file's text. `ChangelogFunctions` and its parameter types have the same structure as `@changesets/types`', so one changelog module loads under `@changesets/cli` and here.
|
|
85
|
+
|
|
86
|
+
For `changeset version --snapshot`, pass `snapshot: { tag?, commit?, timestamp }` to `ReleasePlan.read(root, { snapshot })` or `ReleasePlan.assemble`.
|
|
87
|
+
|
|
79
88
|
## Lint changesets
|
|
80
89
|
|
|
81
|
-
`ChangesetLint` holds
|
|
90
|
+
`ChangesetLint` holds lint rules that hold under any house style: only what the changesets tool itself refuses a file for. `CF001` checks for a front matter block that is YAML and, when not empty, a mapping; `CF002`, for a package name in every key; `CF003`, for a release type in every value; and `CF004`, given the workspace's package names, that each named package exists. Run the defaults in markdownlint-cli2, beside your own style's rules:
|
|
82
91
|
|
|
83
92
|
```js
|
|
84
93
|
// .markdownlint-cli2.mjs
|
|
85
94
|
import { MarkdownlintAdapter } from "@effected/markdown-lint";
|
|
86
95
|
import { ChangesetLint } from "@effected/changesets/lint";
|
|
87
96
|
|
|
88
|
-
export default { customRules: MarkdownlintAdapter.rules(ChangesetLint.
|
|
97
|
+
export default { customRules: MarkdownlintAdapter.rules(ChangesetLint.defaults) };
|
|
89
98
|
```
|
|
90
99
|
|
|
91
100
|
Or lint a file's text directly, with no Effect runtime:
|
|
@@ -93,22 +102,24 @@ Or lint a file's text directly, with no Effect runtime:
|
|
|
93
102
|
```ts
|
|
94
103
|
import { ChangesetLint } from "@effected/changesets/lint";
|
|
95
104
|
|
|
96
|
-
const findings = ChangesetLint.lint(text);
|
|
105
|
+
const findings = ChangesetLint.lint(text, { packages: ["@my/pkg"], rules: houseRules });
|
|
97
106
|
```
|
|
98
107
|
|
|
99
|
-
The
|
|
108
|
+
The defaults agree with `@changesets/parse`: a file it parses fails none of them, and a file it refuses fails one. A section-heading or summary style is not included; bring your own as `rules`.
|
|
100
109
|
|
|
101
110
|
## What's in the box
|
|
102
111
|
|
|
103
112
|
- `ChangesetFile`: `parseSync` and `parse` for one changeset's text, to a `ParsedChangeset` of releases and summary.
|
|
104
113
|
- `PendingChangesets`: `read` and `readSync` for the changesets under `.changeset/`, sorted by file name, then those a pre-release consumed under `.changeset/pre/`, to `PendingChangeset` values.
|
|
105
114
|
- `PreState`: `read` decodes `.changeset/pre.json` to an `Option`, empty outside pre-release mode. It never rewrites the file.
|
|
106
|
-
- `ChangesetConfig`: `read` decodes `.changeset/config.json
|
|
107
|
-
- `ReleasePlan`: `read` as above, and `assemble` to plan from packages, changesets, a config and an optional `PreState` you already hold, returning a `Result` with no IO. A plan holds `releases`, the `changesets` it was made from (in pre mode, less those a pre-release consumed)
|
|
115
|
+
- `ChangesetConfig`: `read` decodes `.changeset/config.json`, `changelog` and `snapshot` included. Keys it does not model stay on `extra`.
|
|
116
|
+
- `ReleasePlan`: `read` as above, and `assemble` to plan from packages, changesets, a config and an optional `PreState` you already hold, returning a `Result` with no IO. Both take an optional snapshot. A plan holds `releases`, the `changesets` it was made from (in pre mode, less those a pre-release consumed), its `preState` when there is one, and whether it is a snapshot. `edits` turns a plan into `ReleaseEdits`.
|
|
117
|
+
- `ReleaseEdits`, `ManifestEdit`, `RangeEdit` and `ChangesetMove`: what `changeset version` writes, as data.
|
|
118
|
+
- `Changelog`: `entry` and `insert`, over a `ChangelogFunctions` module.
|
|
108
119
|
- `PlannedRelease`: one package's `name`, `type`, `oldVersion`, `newVersion` and contributing `changesets`.
|
|
109
120
|
- `BumpType`: the `patch | minor | major` schema, and `ReleaseType`, which adds `none`.
|
|
110
|
-
- `ChangesetLint` (from `@effected/changesets/lint`): the
|
|
111
|
-
- Errors: `ChangesetParseError`, `ChangesetConfigError`, `UnknownPackageError`.
|
|
121
|
+
- `ChangesetLint` (from `@effected/changesets/lint`): the style-neutral front-matter rules, as above.
|
|
122
|
+
- Errors: `ChangesetParseError`, `ChangesetConfigError`, `UnknownPackageError`, `SnapshotPreModeError`, `SnapshotTemplateError`, `MissingPackageError`, `ChangelogError`.
|
|
112
123
|
|
|
113
124
|
## Rules worth knowing
|
|
114
125
|
|
|
@@ -145,7 +156,10 @@ Answered differently:
|
|
|
145
156
|
- A root with a catalog-only `pnpm-workspace.yaml` answers for itself, where changesets climbs to any enclosing workspace.
|
|
146
157
|
- A version changesets cannot bump, such as `=1.2.0` (npm's loose parse reads it, but changesets bumps with strict `semver.inc`), and a `pre.json` with no `tag` or an unknown `mode`, fail with a typed error. changesets crashes or plans nonsense versions for them.
|
|
147
158
|
- An older `pre.json` that lists consumed changesets by id is planned as changesets settles on after moving those files, and nothing is written.
|
|
148
|
-
-
|
|
159
|
+
- A snapshot is refused in pre mode, as `changeset version` refuses it, and an empty snapshot tag or commit counts as none.
|
|
160
|
+
- A Ruby-style `~>` range is not read as a range: it never ripples and is never rewritten.
|
|
161
|
+
- `ReleaseEdits` leaves out an edit that would write the value already there; the files end up the same.
|
|
162
|
+
- A changelog module's `packageJson` holds the fields this package reads from a manifest, not the whole file.
|
|
149
163
|
|
|
150
164
|
## License
|
|
151
165
|
|