@effected/changesets 0.0.0-stage → 0.2.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 +27 -0
- package/ChangesetConfig.js +102 -0
- package/ChangesetFile.js +68 -0
- package/ChangesetLint.js +108 -0
- package/LICENSE +21 -0
- package/PendingChangesets.js +210 -0
- package/PreState.js +54 -0
- package/README.md +151 -2
- package/ReleasePlan.js +587 -0
- package/errors.js +51 -0
- package/index.d.ts +483 -0
- package/index.js +9 -0
- package/internal/lint/content-structure.js +37 -0
- package/internal/lint/dependency-table-format.js +117 -0
- package/internal/lint/docs.js +72 -0
- package/internal/lint/heading-hierarchy.js +32 -0
- package/internal/lint/required-sections.js +23 -0
- package/internal/lint/uncategorized-content.js +22 -0
- package/lint.d.ts +92 -0
- package/lint.js +3 -0
- package/package.json +65 -5
- package/tsdoc-metadata.json +11 -0
package/README.md
CHANGED
|
@@ -1,3 +1,152 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @effected/changesets
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@effected/changesets)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://nodejs.org/)
|
|
6
|
+
[](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
|