@effected/changesets 0.0.0-stage → 0.1.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/BumpType.js ADDED
@@ -0,0 +1,27 @@
1
+ import { Schema } from "effect";
2
+
3
+ // src/BumpType.ts
4
+ /**
5
+ * A semver bump a changeset can request: `patch`, `minor` or `major`.
6
+ *
7
+ * @public
8
+ */
9
+ const BumpType = Schema.Literals([
10
+ "patch",
11
+ "minor",
12
+ "major"
13
+ ]);
14
+ /**
15
+ * What a changeset can say about a package: a {@link (BumpType:variable)}, or `none`, which names the package and
16
+ * moves no version.
17
+ *
18
+ * @public
19
+ */
20
+ const ReleaseType = Schema.Literals([
21
+ "patch",
22
+ "minor",
23
+ "major",
24
+ "none"
25
+ ]);
26
+
27
+ export { BumpType, ReleaseType };
@@ -0,0 +1,102 @@
1
+ import { ChangesetConfigError } from "./errors.js";
2
+ import { Effect, FileSystem, Path, Schema } from "effect";
3
+
4
+ // src/ChangesetConfig.ts
5
+ const Groups = Schema.Array(Schema.Array(Schema.String));
6
+ const expandPrivatePackages = (json) => {
7
+ const flag = json?.privatePackages;
8
+ return typeof flag === "boolean" ? {
9
+ ...json,
10
+ privatePackages: {
11
+ tag: flag,
12
+ version: flag
13
+ }
14
+ } : json;
15
+ };
16
+ /**
17
+ * The decoded `.changeset/config.json`, with the defaults changesets
18
+ * documents. Keys the schema does not model (`changelog`, `$schema`,
19
+ * `format`, ...) are kept on the instance rather than rejected.
20
+ *
21
+ * @public
22
+ */
23
+ var ChangesetConfig = class ChangesetConfig extends Schema.Class("ChangesetConfig")({
24
+ /** The branch releases are cut against. Defaults to `main`. */
25
+ baseBranch: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed("main"))),
26
+ /**
27
+ * Groups of packages that always release together at one version: when
28
+ * one bumps, every member does, by the group's highest bump, from the
29
+ * group's highest current version. Entries are globs over the
30
+ * workspace's names, with `!` negation applying in order.
31
+ */
32
+ fixed: Groups.pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
33
+ /**
34
+ * Groups of packages whose versions are kept in step: the members that
35
+ * release take the group's highest bump from its highest current version,
36
+ * and members with nothing to release stay out. Entries are globs, as in
37
+ * `fixed`.
38
+ */
39
+ linked: Groups.pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
40
+ /**
41
+ * Packages that never bump: globs over the workspace's package names, with
42
+ * `!` negation applying in order. A release plan can still list a matching
43
+ * package as `none` when it depends on something in the plan.
44
+ */
45
+ ignore: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
46
+ /**
47
+ * The smallest bump for which `changeset version` rewrites an internal
48
+ * dependency range. It is not the bump a dependent receives: a release plan
49
+ * always bumps a dependent `patch`.
50
+ */
51
+ updateInternalDependencies: Schema.Literals(["patch", "minor"]).pipe(Schema.withDecodingDefaultKey(Effect.succeed("patch"))),
52
+ /**
53
+ * Whether private packages are tagged and versioned. Both default to `false`,
54
+ * as `@changesets/config` has them, so a private package releases only when
55
+ * the file opts in. {@link ChangesetConfig.read} also takes the boolean form,
56
+ * which sets both.
57
+ */
58
+ privatePackages: Schema.Struct({
59
+ tag: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false))),
60
+ version: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false)))
61
+ }).pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
62
+ /** The publish access level. Defaults to `restricted`. */
63
+ access: Schema.Literals(["public", "restricted"]).pipe(Schema.withDecodingDefaultKey(Effect.succeed("restricted"))),
64
+ /** `false`, `true` or a commit-message generator spec; carried as-is. */
65
+ commit: Schema.Unknown.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false))),
66
+ /**
67
+ * Every key of the file the schema does not model, such as `changelog` or
68
+ * `$schema`. A file key literally named `extra` is not carried: the field
69
+ * name is reserved.
70
+ */
71
+ extra: Schema.Record(Schema.String, Schema.Unknown).pipe(Schema.withDecodingDefaultKey(Effect.succeed({})))
72
+ }) {
73
+ /**
74
+ * Read and decode `<root>/.changeset/config.json`.
75
+ *
76
+ * Fails with {@link ChangesetConfigError} when the file is missing
77
+ * (`reason: "missing"`), is not JSON, or has a malformed value. Whether the
78
+ * repository is in pre-release mode is `.changeset/pre.json`, which
79
+ * {@link PreState.read} reads.
80
+ *
81
+ * @param root - The repository root.
82
+ */
83
+ static read = Effect.fn("ChangesetConfig.read")(function* (root) {
84
+ const fs = yield* FileSystem.FileSystem;
85
+ const path = yield* Path.Path;
86
+ const dir = path.join(root, ".changeset");
87
+ const text = yield* fs.readFileString(path.join(dir, "config.json")).pipe(Effect.catch((error) => error.reason._tag === "NotFound" ? Effect.fail(new ChangesetConfigError({ reason: "missing" })) : Effect.fail(error)));
88
+ const json = yield* Effect.try({
89
+ try: () => JSON.parse(text),
90
+ catch: (cause) => new ChangesetConfigError({ reason: `not valid JSON: ${cause.message}` })
91
+ });
92
+ const decoded = yield* Schema.decodeUnknownEffect(ChangesetConfig)(expandPrivatePackages(json)).pipe(Effect.mapError((error) => new ChangesetConfigError({ reason: error.message })));
93
+ const known = new Set(Object.keys(ChangesetConfig.fields));
94
+ const extra = Object.fromEntries(Object.entries(json).filter(([key]) => !known.has(key)));
95
+ return ChangesetConfig.make({
96
+ ...decoded,
97
+ extra
98
+ });
99
+ });
100
+ };
101
+
102
+ export { ChangesetConfig };
@@ -0,0 +1,68 @@
1
+ import { ReleaseType } from "./BumpType.js";
2
+ import { ChangesetParseError } from "./errors.js";
3
+ import { Effect, Result, Schema } from "effect";
4
+ import { Yaml } from "@effected/yaml";
5
+
6
+ // src/ChangesetFile.ts
7
+ /**
8
+ * One parsed changeset: the packages it releases and its summary text.
9
+ *
10
+ * @public
11
+ */
12
+ var ParsedChangeset = class extends Schema.Class("ParsedChangeset")({
13
+ /** Package name to requested release type, in file order. */
14
+ releases: Schema.ReadonlyMap(Schema.String, ReleaseType),
15
+ /** The markdown after the front matter. */
16
+ summary: Schema.String
17
+ }) {};
18
+ const Releases = Schema.Record(Schema.String, ReleaseType);
19
+ const decodeReleases = Schema.decodeUnknownResult(Releases);
20
+ const fail = (reason, line) => Result.fail(new ChangesetParseError({
21
+ reason,
22
+ ...line === void 0 ? {} : { line }
23
+ }));
24
+ const parseText = (text) => {
25
+ const lines = text.split("\n");
26
+ const isFence = (line) => line !== void 0 && line.replace(/\r$/, "") === "---";
27
+ if (!isFence(lines[0])) return fail("missing front matter: the file must start with a --- line", 1);
28
+ const close = lines.findIndex((line, index) => index > 0 && isFence(line));
29
+ if (close === -1) return fail("unterminated front matter: no closing --- line", 1);
30
+ const block = lines.slice(1, close).join("\n");
31
+ const summary = lines.slice(close + 1).join("\n").replace(/^\r?\n/, "");
32
+ const value = block.trim() === "" ? Result.succeed({}) : Yaml.parseResult(block);
33
+ return Result.match(value, {
34
+ onFailure: (error) => fail(`front matter is not valid YAML: ${error.message}`, (error.diagnostics[0]?.line ?? 0) + 2),
35
+ onSuccess: (parsed) => Result.match(decodeReleases(parsed ?? {}), {
36
+ onFailure: (error) => fail(`front matter must map package names to patch, minor, major or none: ${error.message}`, 2),
37
+ onSuccess: (releases) => Result.succeed(ParsedChangeset.make({
38
+ releases: new Map(Object.entries(releases)),
39
+ summary
40
+ }))
41
+ })
42
+ });
43
+ };
44
+ /**
45
+ * Parsing a changeset markdown file: YAML front matter mapping package names
46
+ * to release types, then the summary.
47
+ *
48
+ * @public
49
+ */
50
+ var ChangesetFile = class ChangesetFile {
51
+ /**
52
+ * Parse a changeset synchronously.
53
+ *
54
+ * @param text - The file contents.
55
+ * @returns A `Result` of the parsed changeset or a {@link ChangesetParseError}.
56
+ */
57
+ static parseSync(text) {
58
+ return parseText(text);
59
+ }
60
+ /**
61
+ * Parse a changeset; the `Effect` form of {@link ChangesetFile.parseSync}.
62
+ *
63
+ * @param text - The file contents.
64
+ */
65
+ static parse = Effect.fn("ChangesetFile.parse")((text) => Effect.fromResult(ChangesetFile.parseSync(text)));
66
+ };
67
+
68
+ export { ChangesetFile, ParsedChangeset };
@@ -0,0 +1,108 @@
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";
7
+
8
+ // src/ChangesetLint.ts
9
+ /**
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.
14
+ *
15
+ * @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.
31
+ *
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:
36
+ *
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.
55
+ *
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.
60
+ *
61
+ * @example
62
+ * ```ts
63
+ * import { MarkdownlintAdapter } from "@effected/markdown-lint";
64
+ * import { ChangesetLint } from "@effected/changesets/lint";
65
+ *
66
+ * // .markdownlint-cli2.mjs
67
+ * export default { customRules: MarkdownlintAdapter.rules(ChangesetLint.rules) };
68
+ * ```
69
+ *
70
+ * @public
71
+ */
72
+ 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;
83
+ /**
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.
87
+ */
88
+ static rules = [
89
+ HeadingHierarchy,
90
+ RequiredSections,
91
+ ContentStructure,
92
+ DependencyTableFormat,
93
+ UncategorizedContent
94
+ ];
95
+ /**
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.
99
+ *
100
+ * @param source - The changeset file's text.
101
+ * @param options - Parse options, passed to `MarkdownLint.lint`.
102
+ */
103
+ static lint(source, options) {
104
+ return MarkdownLint.lint(source, ChangesetLint.rules, options);
105
+ }
106
+ };
107
+
108
+ export { ChangesetLint };
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 C. Spencer Beggs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,128 @@
1
+ import { ReleaseType } from "./BumpType.js";
2
+ import { ChangesetFile } from "./ChangesetFile.js";
3
+ import { ChangesetParseError } from "./errors.js";
4
+ import { Effect, FileSystem, Path, PlatformError, Result, Schema } from "effect";
5
+ import { readFileSync, readdirSync } from "node:fs";
6
+
7
+ // src/PendingChangesets.ts
8
+ /**
9
+ * One pending changeset read from `.changeset/`.
10
+ *
11
+ * @public
12
+ */
13
+ var PendingChangeset = class extends Schema.Class("PendingChangeset")({
14
+ /**
15
+ * The file name, relative to `.changeset/`: `pre/<name>.md` for a
16
+ * changeset an earlier pre-release consumed.
17
+ */
18
+ file: Schema.String,
19
+ /** Package name to requested release type, in file order. */
20
+ releases: Schema.ReadonlyMap(Schema.String, ReleaseType),
21
+ /** The markdown after the front matter. */
22
+ summary: Schema.String
23
+ }) {};
24
+ /** The directory, under `.changeset/`, holding the changesets a pre-release consumed. */
25
+ const PRE = "pre";
26
+ const CONTEXT_FILES = /* @__PURE__ */ new Set([
27
+ "AGENTS.md",
28
+ "CLAUDE.md",
29
+ "GEMINI.md"
30
+ ]);
31
+ const isChangesetName = (name) => name.endsWith(".md") && !name.startsWith(".") && !/^README\.md$/i.test(name) && !CONTEXT_FILES.has(name);
32
+ const selectNames = (names) => names.filter(isChangesetName).sort();
33
+ const withFile = (file, error) => new ChangesetParseError({
34
+ reason: error.reason,
35
+ file,
36
+ ...error.line === void 0 ? {} : { line: error.line }
37
+ });
38
+ const toPending = (file, text) => Result.match(ChangesetFile.parseSync(text), {
39
+ onFailure: (error) => Result.fail(withFile(file, error)),
40
+ onSuccess: (parsed) => Result.succeed(PendingChangeset.make({
41
+ file,
42
+ releases: parsed.releases,
43
+ summary: parsed.summary
44
+ }))
45
+ });
46
+ const nodeErrorTag = (code) => {
47
+ switch (code) {
48
+ case "ENOENT": return "NotFound";
49
+ case "EACCES":
50
+ case "EPERM": return "PermissionDenied";
51
+ case "EISDIR":
52
+ case "ENOTDIR": return "BadResource";
53
+ default: return "Unknown";
54
+ }
55
+ };
56
+ const toPlatformError = (method, path, cause) => PlatformError.systemError({
57
+ _tag: nodeErrorTag(cause?.code),
58
+ module: "PendingChangesets",
59
+ method,
60
+ pathOrDescriptor: path,
61
+ cause
62
+ });
63
+ const isNotFound = (error) => error.reason._tag === "NotFound";
64
+ /**
65
+ * Reading the pending changesets under a repository's `.changeset/`
66
+ * directory.
67
+ *
68
+ * @public
69
+ */
70
+ var PendingChangesets = class {
71
+ /**
72
+ * Read every pending changeset under `<root>/.changeset/`, ordered by file
73
+ * name, then those under `<root>/.changeset/pre/`, which a pre-release
74
+ * keeps after consuming them, as `pre/<name>.md`. A readme in any case,
75
+ * `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, dotfiles and non-`.md` files are
76
+ * skipped; a missing directory answers `[]`.
77
+ *
78
+ * @param root - The repository root.
79
+ */
80
+ static read = Effect.fn("PendingChangesets.read")(function* (root) {
81
+ const fs = yield* FileSystem.FileSystem;
82
+ const path = yield* Path.Path;
83
+ 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}`)];
88
+ return yield* Effect.forEach(files, (file) => fs.readFileString(path.join(dir, file)).pipe(Effect.flatMap((text) => Effect.fromResult(toPending(file, text)))));
89
+ });
90
+ /**
91
+ * Synchronous {@link PendingChangesets.read} over `node:fs`, for callers
92
+ * that run before any Effect runtime exists.
93
+ *
94
+ * @param root - The repository root.
95
+ */
96
+ 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);
112
+ 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);
121
+ if (Result.isFailure(parsed)) return Result.fail(parsed.failure);
122
+ pending.push(parsed.success);
123
+ }
124
+ return Result.succeed(pending);
125
+ }
126
+ };
127
+
128
+ export { PendingChangeset, PendingChangesets };
package/PreState.js ADDED
@@ -0,0 +1,54 @@
1
+ import { ChangesetConfigError } from "./errors.js";
2
+ import { Effect, FileSystem, Option, Path, Schema } from "effect";
3
+
4
+ // src/PreState.ts
5
+ /**
6
+ * The decoded `.changeset/pre.json`: the repository is in pre-release mode
7
+ * (`changeset pre enter <tag>`), or leaving it (`changeset pre exit`).
8
+ *
9
+ * @remarks
10
+ * In `pre` mode a release plan appends `-<tag>.<n>` to every bumped version
11
+ * and leaves out the changesets under `.changeset/pre/`, which an earlier
12
+ * pre-release already consumed. In `exit` mode those changesets count again,
13
+ * no suffix is appended, and every package still on a numbered prerelease
14
+ * bumps at least `patch`. The file's other keys are not kept.
15
+ *
16
+ * @public
17
+ */
18
+ var PreState = class PreState extends Schema.Class("PreState")({
19
+ /** `pre` while pre-releasing, `exit` once `changeset pre exit` has run. */
20
+ mode: Schema.Literals(["pre", "exit"]),
21
+ /** The prerelease tag, such as `next` or `beta`. */
22
+ tag: Schema.String,
23
+ /**
24
+ * The changesets an earlier pre-release consumed, by id (the file name
25
+ * without `.md`), as the older `pre.json` layout lists them. The current
26
+ * layout moves those files into `.changeset/pre/` instead.
27
+ */
28
+ changesets: Schema.optionalKey(Schema.Array(Schema.String))
29
+ }) {
30
+ /**
31
+ * Read `<root>/.changeset/pre.json`: `Option.none()` when the repository
32
+ * is not in pre-release mode.
33
+ *
34
+ * Fails with {@link ChangesetConfigError} when the file is not JSON or does
35
+ * not match the shape. Unlike `@changesets/pre`, it never rewrites an
36
+ * older-layout file or moves a changeset.
37
+ *
38
+ * @param root - The repository root.
39
+ */
40
+ static read = Effect.fn("PreState.read")(function* (root) {
41
+ const fs = yield* FileSystem.FileSystem;
42
+ const path = yield* Path.Path;
43
+ const text = yield* fs.readFileString(path.join(root, ".changeset", "pre.json")).pipe(Effect.map(Option.some), Effect.catch((error) => error.reason._tag === "NotFound" ? Effect.succeed(Option.none()) : Effect.fail(error)));
44
+ if (Option.isNone(text)) return Option.none();
45
+ const json = yield* Effect.try({
46
+ try: () => JSON.parse(text.value),
47
+ catch: (cause) => new ChangesetConfigError({ reason: `pre.json is not valid JSON: ${cause.message}` })
48
+ });
49
+ const decoded = yield* Schema.decodeUnknownEffect(PreState)(json).pipe(Effect.mapError((error) => new ChangesetConfigError({ reason: `pre.json: ${error.message}` })));
50
+ return Option.some(decoded);
51
+ });
52
+ };
53
+
54
+ export { PreState };
package/README.md CHANGED
@@ -1,3 +1,152 @@
1
- # Temporary Holding Version
1
+ # @effected/changesets
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/@effected%2Fchangesets?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/changesets)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
5
+ [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
6
+ [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
7
+
8
+ Changeset files, `.changeset/config.json` and the release plan as Effect schemas and pure functions. Read what a repository's pending changesets release, including the packages bumped only because a dependency moved, without carrying the changesets packages at runtime.
9
+
10
+ > **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
11
+ > Effect v4 (`effect` `~4.1.0`) and still in `0.x` development. Stable Effect
12
+ > makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
13
+ > `@effect/*` versions on the line the kit is built and tested against, install
14
+ > [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected).
15
+ >
16
+ > **Stability: unstable.** This package's API surface is not yet considered
17
+ > complete and may change across `0.x` releases. Pin an exact version — even a
18
+ > package marked *stable* before `1.0.0` can introduce a breaking change by
19
+ > accident, and an exact pin turns that into a type-check error rather than a
20
+ > runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
21
+
22
+ ## Why @effected/changesets
23
+
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
+
26
+ It reads and plans only. Nothing here writes a changeset, versions a package or publishes one, so `changeset version` stays where it is.
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).
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ npm install @effected/changesets effect
34
+ ```
35
+
36
+ ```bash
37
+ pnpm add @effected/changesets effect
38
+ ```
39
+
40
+ Requires Node.js >=24.11.0. `effect` v4 is a peer dependency.
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.
43
+
44
+ ```bash
45
+ pnpm add @effected/markdown @effected/markdown-lint
46
+ ```
47
+
48
+ All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
49
+
50
+ ## Quick start
51
+
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
+
54
+ ```ts
55
+ import { NodeFileSystem, NodePath } from "@effect/platform-node";
56
+ import { ReleasePlan } from "@effected/changesets";
57
+ import { WorkspaceDiscovery, WorkspaceRoot } from "@effected/workspaces";
58
+ import { Effect, Layer } from "effect";
59
+
60
+ const root = process.cwd();
61
+
62
+ const AppLayer = WorkspaceDiscovery.layer({ cwd: root }).pipe(
63
+ Layer.provide(WorkspaceRoot.layer),
64
+ Layer.provideMerge(Layer.merge(NodeFileSystem.layer, NodePath.layer)),
65
+ );
66
+
67
+ const program = Effect.gen(function* () {
68
+ const plan = yield* ReleasePlan.read(root);
69
+ for (const release of plan.releases) {
70
+ yield* Effect.log(`${release.name}: ${release.oldVersion} -> ${release.newVersion} (${release.type})`);
71
+ }
72
+ }).pipe(Effect.provide(AppLayer));
73
+
74
+ Effect.runPromise(program);
75
+ ```
76
+
77
+ 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
+ ## Lint changesets
80
+
81
+ `ChangesetLint` holds the changeset style rules CSH001 to CSH005, defined once over `@effected/markdown` trees. Run them in markdownlint-cli2:
82
+
83
+ ```js
84
+ // .markdownlint-cli2.mjs
85
+ import { MarkdownlintAdapter } from "@effected/markdown-lint";
86
+ import { ChangesetLint } from "@effected/changesets/lint";
87
+
88
+ export default { customRules: MarkdownlintAdapter.rules(ChangesetLint.rules) };
89
+ ```
90
+
91
+ Or lint a file's text directly, with no Effect runtime:
92
+
93
+ ```ts
94
+ import { ChangesetLint } from "@effected/changesets/lint";
95
+
96
+ const findings = ChangesetLint.lint(text);
97
+ ```
98
+
99
+ The rules give the same verdicts, messages and lines as savvy-web/systems' markdownlint rules, which they port.
100
+
101
+ ## What's in the box
102
+
103
+ - `ChangesetFile`: `parseSync` and `parse` for one changeset's text, to a `ParsedChangeset` of releases and summary.
104
+ - `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
+ - `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.
108
+ - `PlannedRelease`: one package's `name`, `type`, `oldVersion`, `newVersion` and contributing `changesets`.
109
+ - `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`.
112
+
113
+ ## Rules worth knowing
114
+
115
+ The plan follows changesets, and some of its rules surprise people:
116
+
117
+ - A package reached as a dependent always bumps `patch`. `updateInternalDependencies` does not change that.
118
+ - A private package releases only if `privatePackages.version` is on, and it defaults to off.
119
+ - Entries in `ignore` are globs, with `!` negation applied in order.
120
+ - `catalog:`, `link:`, `npm:` and a range the dependency has already left draw no dependency edge, so they never ripple.
121
+ - A package reached only through `devDependencies` is listed as `none`.
122
+ - A bump completes a prerelease it is heading for: a `major` of `2.0.0-rc.1` is `2.0.0`.
123
+ - In a repository whose only package is the root, the root is the package.
124
+ - A changeset may name a package `none`: it is listed, and moves nothing unless something else bumps it.
125
+ - A `fixed` group with any member releasing releases every member, at the group's highest bump, from the group's highest current version, which is the `oldVersion` each member reports. A `linked` group does the same for only the members that release.
126
+ - In pre-release mode each bumped version gains `-<tag>.<n>`, and the changesets under `.changeset/pre/` are left out, because an earlier pre-release consumed them. In exit mode they count again, and every package on a numbered prerelease bumps at least `patch`.
127
+ - A leading `v` on a version is dropped, as npm drops it: `v1.0.0` bumps to `1.0.1`.
128
+
129
+ ## Differences from changesets
130
+
131
+ Refused here, planned by changesets:
132
+
133
+ - A changeset naming a root that `packages:` lists alongside other packages fails with `UnknownPackageError`.
134
+
135
+ Planned here, refused by changesets:
136
+
137
+ - A changeset mixing skipped and released packages.
138
+ - A public package depending on a skipped one.
139
+ - `privatePackages` with `tag` on and `version` off.
140
+ - A `pnpm-workspace.yaml` with `packages: []` or patterns matching nothing, which plan the root.
141
+
142
+ Answered differently:
143
+
144
+ - A version-less package is left out of the plan rather than listed with no versions.
145
+ - A root with a catalog-only `pnpm-workspace.yaml` answers for itself, where changesets climbs to any enclosing workspace.
146
+ - 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
+ - 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.
149
+
150
+ ## License
151
+
152
+ MIT