@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/ChangesetLint.js CHANGED
@@ -1,62 +1,106 @@
1
- import { ContentStructure } from "./internal/lint/content-structure.js";
2
- import { DependencyTableFormat } from "./internal/lint/dependency-table-format.js";
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
- * The changeset style rules CSH001 to CSH005, each defined once as a
11
- * `LintRule` over `@effected/markdown` trees, so one definition runs in
12
- * `MarkdownLint` and, through `MarkdownlintAdapter`, in markdownlint and
13
- * markdownlint-cli2.
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
- * The rules check a changeset's body, whatever its front matter says:
17
- *
18
- * - `CSH001` `changeset-heading-hierarchy`: no `h1`, and no heading that
19
- * skips a level.
20
- * - `CSH002` `changeset-required-sections`: every `h2` names one of the
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
- * Messages, lines and columns are savvy-web/systems' own, which wrote the
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
- * - Only top-level blocks are sections: a heading, list or code block
38
- * inside a list item or a block quote is not checked by CSH001, CSH002 or
39
- * CSH003.
40
- * - A heading or table cell is compared as written, with backslash escapes
41
- * resolved and inline formatting kept: a heading of `Features` in a code
42
- * span and `## *Bug Fixes*` are unknown sections, and a `From` cell of
43
- * `1.0.0` in a code span is not a version. That verdict looks stricter than an author
44
- * expects, but it is what markdownlint enforces.
45
- * - CSH003 checks fenced code only, since an indented block has no fence to
46
- * name a language on, and calls a list item empty unless it holds a
47
- * paragraph: an item of only an HTML comment, a nested list or a heading is
48
- * empty, and an item of only an image is not.
49
- * - A table row shorter than the header has too few columns. The parsed tree
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
- * One difference remains, and it is the parser's, not a rule's: after an
57
- * indented code block, markdownlint's micromark reads a bare `- ` line as a
58
- * paragraph, where CommonMark reads an empty list item, so CSH003 reports an
59
- * empty item there and markdownlint does not.
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.rules) };
111
+ * export default { customRules: MarkdownlintAdapter.rules(ChangesetLint.defaults) };
68
112
  * ```
69
113
  *
70
114
  * @public
71
115
  */
72
116
  var ChangesetLint = class ChangesetLint {
73
- /** CSH001: headings start at `h2` and never skip a level. */
74
- static headingHierarchy = HeadingHierarchy;
75
- /** CSH002: every `h2` names a changeset category. */
76
- static requiredSections = RequiredSections;
77
- /** CSH003: sections have content, fences a language, list items text. */
78
- static contentStructure = ContentStructure;
79
- /** CSH004: nothing comes before the first category heading. */
80
- static uncategorizedContent = UncategorizedContent;
81
- /** CSH005: a `Dependencies` section holds a valid dependency table. */
82
- static dependencyTableFormat = DependencyTableFormat;
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
- * The five rules in the order savvy-web/systems' linter runs them, CSH005
85
- * before CSH004, which is the order `MarkdownLint` reports their findings
86
- * in.
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 rules = [
89
- HeadingHierarchy,
90
- RequiredSections,
91
- ContentStructure,
92
- DependencyTableFormat,
93
- UncategorizedContent
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 with all five rules: `MarkdownLint.lint`
97
- * over {@link ChangesetLint.rules}. Line numbers count the whole file, front
98
- * matter included.
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 - Parse options, passed to `MarkdownLint.lint`.
161
+ * @param options - The rules and the parse options.
102
162
  */
103
163
  static lint(source, options) {
104
- return MarkdownLint.lint(source, ChangesetLint.rules, options);
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
 
@@ -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 list = (directory) => fs.readDirectory(directory).pipe(Effect.catch((error) => isNotFound(error) ? Effect.succeed([]) : Effect.fail(error)));
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
- let end = root.length;
98
- while (end > 0 && (root[end - 1] === "/" || root[end - 1] === "\\")) end--;
99
- const dir = `${root.slice(0, end)}/.changeset`;
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 [...names.success, ...consumed.success.map((name) => `${PRE}/${name}`)]) {
114
- let text;
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 plans only. Nothing here writes a changeset, versions a package or publishes one, so `changeset version` stays where it is.
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` is a test-only dependency, and the test suite requires the same plan from both over a set of small pnpm workspaces. The cases where this package deliberately differs are listed under [Differences from changesets](#differences-from-changesets).
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 { NodeFileSystem, NodePath } from "@effect/platform-node";
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 the changeset style rules CSH001 to CSH005, defined once over `@effected/markdown` trees. Run them in markdownlint-cli2:
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.rules) };
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 rules give the same verdicts, messages and lines as savvy-web/systems' markdownlint rules, which they port.
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`. Keys it does not model stay on `extra`.
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) and its `preState`, when there is one.
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 five lint rules, as above.
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
- - Snapshot versions are not planned: they are a flag on `changeset version`, not part of a release plan.
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