@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
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
// src/internal/lint/docs.ts
|
|
2
|
+
const DOCS_BASE = "https://github.com/savvy-web/systems/blob/main/packages/silk-effects/docs/rules";
|
|
3
|
+
const RULE_DOCS = {
|
|
4
|
+
CSH001: `${DOCS_BASE}/CSH001.md`,
|
|
5
|
+
CSH002: `${DOCS_BASE}/CSH002.md`,
|
|
6
|
+
CSH003: `${DOCS_BASE}/CSH003.md`,
|
|
7
|
+
CSH004: `${DOCS_BASE}/CSH004.md`,
|
|
8
|
+
CSH005: `${DOCS_BASE}/CSH005.md`
|
|
9
|
+
};
|
|
10
|
+
/** The thirteen changeset category headings, in display order. */
|
|
11
|
+
const CATEGORY_HEADINGS = [
|
|
12
|
+
"Breaking Changes",
|
|
13
|
+
"Features",
|
|
14
|
+
"Bug Fixes",
|
|
15
|
+
"Performance",
|
|
16
|
+
"Documentation",
|
|
17
|
+
"Refactoring",
|
|
18
|
+
"Tests",
|
|
19
|
+
"Build System",
|
|
20
|
+
"CI",
|
|
21
|
+
"Dependencies",
|
|
22
|
+
"Maintenance",
|
|
23
|
+
"Reverts",
|
|
24
|
+
"Other"
|
|
25
|
+
];
|
|
26
|
+
const headingSet = new Set(CATEGORY_HEADINGS.map((heading) => heading.toLowerCase()));
|
|
27
|
+
/** Whether `heading` names a category, ignoring case. */
|
|
28
|
+
const isValidHeading = (heading) => headingSet.has(heading.toLowerCase());
|
|
29
|
+
/** A semver version, a protocol specifier, or the em-dash sentinel. */
|
|
30
|
+
const VERSION_RE = /^(—|[~^]?\d+\.\d+\.\d+(?:[-+.][\w.+-]+)?|(?:catalog|workspace|npm|jsr|file|link|portal):[^\s|]+)$/u;
|
|
31
|
+
const BACKSLASH_ESCAPE_RE = /\\([!-/:-@[-`{-~])/g;
|
|
32
|
+
/**
|
|
33
|
+
* A node's text as written, from its first child to its last, with
|
|
34
|
+
* CommonMark backslash escapes resolved: what systems' markdownlint rules
|
|
35
|
+
* read from a micromark heading or cell token. Inline formatting is kept, so
|
|
36
|
+
* a heading of `Features` in a code span reads with its backticks.
|
|
37
|
+
*/
|
|
38
|
+
const writtenText = (source, node) => {
|
|
39
|
+
const first = node.children[0];
|
|
40
|
+
const last = node.children.at(-1);
|
|
41
|
+
if (first === void 0 || last === void 0) return "";
|
|
42
|
+
return source.slice(first.position.start.offset, last.position.end.offset).replace(BACKSLASH_ESCAPE_RE, "$1");
|
|
43
|
+
};
|
|
44
|
+
/** Line breaks as spaces, as markdownlint writes every `errorDetail`. */
|
|
45
|
+
const oneLine = (text) => text.replace(/\r\n?|\n/g, " ");
|
|
46
|
+
/**
|
|
47
|
+
* Where a top-level heading is reported. micromark reads link reference
|
|
48
|
+
* definitions directly above a setext heading, with no blank line between, as
|
|
49
|
+
* the start of the heading's own token, so markdownlint reports that heading
|
|
50
|
+
* on the first definition's line; anywhere else the heading is its own anchor.
|
|
51
|
+
*/
|
|
52
|
+
const headingAnchor = (source, siblings, index) => {
|
|
53
|
+
const heading = siblings[index];
|
|
54
|
+
const end = heading.position.end.offset;
|
|
55
|
+
let start = heading.position.start.offset;
|
|
56
|
+
if (heading.headingStyle !== "setext") return {
|
|
57
|
+
offset: start,
|
|
58
|
+
length: end - start
|
|
59
|
+
};
|
|
60
|
+
for (let previous = index - 1; previous >= 0; previous--) {
|
|
61
|
+
const sibling = siblings[previous];
|
|
62
|
+
if (sibling.type !== "definition") break;
|
|
63
|
+
if (!/^[ \t]*(?:\r\n?|\n)[ \t]*$/.test(source.slice(sibling.position.end.offset, start))) break;
|
|
64
|
+
start = sibling.position.start.offset;
|
|
65
|
+
}
|
|
66
|
+
return {
|
|
67
|
+
offset: start,
|
|
68
|
+
length: end - start
|
|
69
|
+
};
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
export { CATEGORY_HEADINGS, RULE_DOCS, VERSION_RE, headingAnchor, isValidHeading, oneLine, writtenText };
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { RULE_DOCS, headingAnchor } from "./docs.js";
|
|
2
|
+
import { LintRule } from "@effected/markdown-lint";
|
|
3
|
+
|
|
4
|
+
// src/internal/lint/heading-hierarchy.ts
|
|
5
|
+
const HeadingHierarchy = LintRule.make({
|
|
6
|
+
names: ["changeset-heading-hierarchy", "CSH001"],
|
|
7
|
+
description: "Heading hierarchy must start at h2 with no h1 or depth skips",
|
|
8
|
+
tags: ["changeset"],
|
|
9
|
+
information: RULE_DOCS.CSH001,
|
|
10
|
+
check: (context, report) => {
|
|
11
|
+
let previous = 0;
|
|
12
|
+
const children = context.root.children;
|
|
13
|
+
children.forEach((heading, index) => {
|
|
14
|
+
if (heading.type !== "heading") return;
|
|
15
|
+
const at = headingAnchor(context.source, children, index);
|
|
16
|
+
if (heading.depth === 1) {
|
|
17
|
+
report(context.diagnostic({
|
|
18
|
+
at,
|
|
19
|
+
detail: `h1 headings are not allowed in changeset files. Use h2 (##) for top-level sections like "## Features" or "## Bug Fixes". h1 is reserved for the version title generated by the changelog formatter. See: ${RULE_DOCS.CSH001}`
|
|
20
|
+
}));
|
|
21
|
+
return;
|
|
22
|
+
}
|
|
23
|
+
if (previous > 0 && heading.depth > previous + 1) report(context.diagnostic({
|
|
24
|
+
at,
|
|
25
|
+
detail: `Heading level skipped: expected h${previous + 1} or lower, found h${heading.depth}. Headings must increase sequentially (h2 → h3 → h4). Add the missing intermediate level or reduce this heading's depth. See: ${RULE_DOCS.CSH001}`
|
|
26
|
+
}));
|
|
27
|
+
previous = heading.depth;
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
export { HeadingHierarchy };
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { CATEGORY_HEADINGS, RULE_DOCS, headingAnchor, isValidHeading, oneLine, writtenText } from "./docs.js";
|
|
2
|
+
import { LintRule } from "@effected/markdown-lint";
|
|
3
|
+
|
|
4
|
+
// src/internal/lint/required-sections.ts
|
|
5
|
+
const RequiredSections = LintRule.make({
|
|
6
|
+
names: ["changeset-required-sections", "CSH002"],
|
|
7
|
+
description: "Section headings must match known changeset categories",
|
|
8
|
+
tags: ["changeset"],
|
|
9
|
+
information: RULE_DOCS.CSH002,
|
|
10
|
+
check: (context, report) => {
|
|
11
|
+
const children = context.root.children;
|
|
12
|
+
children.forEach((heading, index) => {
|
|
13
|
+
if (heading.type !== "heading" || heading.depth !== 2) return;
|
|
14
|
+
const text = oneLine(writtenText(context.source, heading));
|
|
15
|
+
if (!isValidHeading(text)) report(context.diagnostic({
|
|
16
|
+
at: headingAnchor(context.source, children, index),
|
|
17
|
+
detail: `Unknown section "${text}". Valid h2 headings are: ${CATEGORY_HEADINGS.join(", ")}. Heading comparison is case-insensitive. See: ${RULE_DOCS.CSH002}`
|
|
18
|
+
}));
|
|
19
|
+
});
|
|
20
|
+
}
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
export { RequiredSections };
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { RULE_DOCS } from "./docs.js";
|
|
2
|
+
import { LintRule } from "@effected/markdown-lint";
|
|
3
|
+
|
|
4
|
+
// src/internal/lint/uncategorized-content.ts
|
|
5
|
+
const UncategorizedContent = LintRule.make({
|
|
6
|
+
names: ["changeset-uncategorized-content", "CSH004"],
|
|
7
|
+
description: "All content must be placed under a category heading (## heading)",
|
|
8
|
+
tags: ["changeset"],
|
|
9
|
+
information: RULE_DOCS.CSH004,
|
|
10
|
+
check: (context, report) => {
|
|
11
|
+
for (const node of context.root.children) {
|
|
12
|
+
if (node.type === "heading" && node.depth === 2) break;
|
|
13
|
+
if (node.type === "heading" || node.type === "html" || node.type === "frontmatter") continue;
|
|
14
|
+
report(context.diagnostic({
|
|
15
|
+
at: node,
|
|
16
|
+
detail: `Content must be placed under a category heading (## heading). Move this content under an appropriate section like "## Features" or "## Bug Fixes". If it doesn't fit an existing category, use "## Other". See: ${RULE_DOCS.CSH004}`
|
|
17
|
+
}));
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
export { UncategorizedContent };
|
package/lint.d.ts
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
import { LintDiagnostic, LintRule, MarkdownLintOptions } from "@effected/markdown-lint";
|
|
2
|
+
/**
|
|
3
|
+
* The changeset style rules CSH001 to CSH005, each defined once as a
|
|
4
|
+
* `LintRule` over `@effected/markdown` trees, so one definition runs in
|
|
5
|
+
* `MarkdownLint` and, through `MarkdownlintAdapter`, in markdownlint and
|
|
6
|
+
* markdownlint-cli2.
|
|
7
|
+
*
|
|
8
|
+
* @remarks
|
|
9
|
+
* The rules check a changeset's body, whatever its front matter says:
|
|
10
|
+
*
|
|
11
|
+
* - `CSH001` `changeset-heading-hierarchy`: no `h1`, and no heading that
|
|
12
|
+
* skips a level.
|
|
13
|
+
* - `CSH002` `changeset-required-sections`: every `h2` names one of the
|
|
14
|
+
* thirteen categories (`Breaking Changes`, `Features`, `Bug Fixes`,
|
|
15
|
+
* `Performance`, `Documentation`, `Refactoring`, `Tests`, `Build System`,
|
|
16
|
+
* `CI`, `Dependencies`, `Maintenance`, `Reverts`, `Other`), ignoring case.
|
|
17
|
+
* - `CSH003` `changeset-content-structure`: no empty section, no code fence
|
|
18
|
+
* without a language, no empty list item.
|
|
19
|
+
* - `CSH004` `changeset-uncategorized-content`: no content before the first
|
|
20
|
+
* `h2`.
|
|
21
|
+
* - `CSH005` `changeset-dependency-table-format`: a `Dependencies` section
|
|
22
|
+
* holds a `Dependency | Type | Action | From | To` table whose cells are
|
|
23
|
+
* valid.
|
|
24
|
+
*
|
|
25
|
+
* Messages, lines and columns are savvy-web/systems' own, which wrote the
|
|
26
|
+
* rules. systems implements each rule twice, and where its two engines
|
|
27
|
+
* disagree these follow its markdownlint engine, the one markdownlint-cli2
|
|
28
|
+
* and a pre-commit hook run. That engine reads micromark tokens, so:
|
|
29
|
+
*
|
|
30
|
+
* - Only top-level blocks are sections: a heading, list or code block
|
|
31
|
+
* inside a list item or a block quote is not checked by CSH001, CSH002 or
|
|
32
|
+
* CSH003.
|
|
33
|
+
* - A heading or table cell is compared as written, with backslash escapes
|
|
34
|
+
* resolved and inline formatting kept: a heading of `Features` in a code
|
|
35
|
+
* span and `## *Bug Fixes*` are unknown sections, and a `From` cell of
|
|
36
|
+
* `1.0.0` in a code span is not a version. That verdict looks stricter than an author
|
|
37
|
+
* expects, but it is what markdownlint enforces.
|
|
38
|
+
* - CSH003 checks fenced code only, since an indented block has no fence to
|
|
39
|
+
* name a language on, and calls a list item empty unless it holds a
|
|
40
|
+
* paragraph: an item of only an HTML comment, a nested list or a heading is
|
|
41
|
+
* empty, and an item of only an image is not.
|
|
42
|
+
* - A table row shorter than the header has too few columns. The parsed tree
|
|
43
|
+
* pads it with empty cells, which are not counted.
|
|
44
|
+
* - A setext heading directly under a link reference definition is
|
|
45
|
+
* reported on the definition's line, where micromark starts its token.
|
|
46
|
+
* - A heading over several lines is named on one line, as markdownlint
|
|
47
|
+
* writes every detail.
|
|
48
|
+
*
|
|
49
|
+
* One difference remains, and it is the parser's, not a rule's: after an
|
|
50
|
+
* indented code block, markdownlint's micromark reads a bare `- ` line as a
|
|
51
|
+
* paragraph, where CommonMark reads an empty list item, so CSH003 reports an
|
|
52
|
+
* empty item there and markdownlint does not.
|
|
53
|
+
*
|
|
54
|
+
* @example
|
|
55
|
+
* ```ts
|
|
56
|
+
* import { MarkdownlintAdapter } from "@effected/markdown-lint";
|
|
57
|
+
* import { ChangesetLint } from "@effected/changesets/lint";
|
|
58
|
+
*
|
|
59
|
+
* // .markdownlint-cli2.mjs
|
|
60
|
+
* export default { customRules: MarkdownlintAdapter.rules(ChangesetLint.rules) };
|
|
61
|
+
* ```
|
|
62
|
+
*
|
|
63
|
+
* @public
|
|
64
|
+
*/
|
|
65
|
+
export declare class ChangesetLint {
|
|
66
|
+
/** CSH001: headings start at `h2` and never skip a level. */
|
|
67
|
+
static readonly headingHierarchy: LintRule;
|
|
68
|
+
/** CSH002: every `h2` names a changeset category. */
|
|
69
|
+
static readonly requiredSections: LintRule;
|
|
70
|
+
/** CSH003: sections have content, fences a language, list items text. */
|
|
71
|
+
static readonly contentStructure: LintRule;
|
|
72
|
+
/** CSH004: nothing comes before the first category heading. */
|
|
73
|
+
static readonly uncategorizedContent: LintRule;
|
|
74
|
+
/** CSH005: a `Dependencies` section holds a valid dependency table. */
|
|
75
|
+
static readonly dependencyTableFormat: LintRule;
|
|
76
|
+
/**
|
|
77
|
+
* The five rules in the order savvy-web/systems' linter runs them, CSH005
|
|
78
|
+
* before CSH004, which is the order `MarkdownLint` reports their findings
|
|
79
|
+
* in.
|
|
80
|
+
*/
|
|
81
|
+
static readonly rules: ReadonlyArray<LintRule>;
|
|
82
|
+
/**
|
|
83
|
+
* Lint one changeset file's text with all five rules: `MarkdownLint.lint`
|
|
84
|
+
* over {@link ChangesetLint.rules}. Line numbers count the whole file, front
|
|
85
|
+
* matter included.
|
|
86
|
+
*
|
|
87
|
+
* @param source - The changeset file's text.
|
|
88
|
+
* @param options - Parse options, passed to `MarkdownLint.lint`.
|
|
89
|
+
*/
|
|
90
|
+
static lint(source: string, options?: MarkdownLintOptions): ReadonlyArray<LintDiagnostic>;
|
|
91
|
+
}
|
|
92
|
+
//# sourceMappingURL=lint.d.ts.map
|
package/lint.js
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,66 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@effected/changesets",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"private": false,
|
|
5
|
+
"description": "Changeset files, `.changeset/config.json` and the release plan as Effect schemas and pure functions.",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"changesets",
|
|
8
|
+
"release",
|
|
9
|
+
"semver",
|
|
10
|
+
"effect",
|
|
11
|
+
"schema",
|
|
12
|
+
"effected"
|
|
13
|
+
],
|
|
14
|
+
"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/changesets#readme",
|
|
15
|
+
"bugs": {
|
|
16
|
+
"url": "https://github.com/spencerbeggs/effected/issues"
|
|
17
|
+
},
|
|
18
|
+
"repository": {
|
|
19
|
+
"type": "git",
|
|
20
|
+
"url": "git+https://github.com/spencerbeggs/effected.git",
|
|
21
|
+
"directory": "packages/changesets"
|
|
22
|
+
},
|
|
23
|
+
"license": "MIT",
|
|
24
|
+
"author": {
|
|
25
|
+
"name": "C. Spencer Beggs",
|
|
26
|
+
"email": "spencer@beggs.codes",
|
|
27
|
+
"url": "https://spencerbeg.gs"
|
|
28
|
+
},
|
|
29
|
+
"sideEffects": false,
|
|
30
|
+
"type": "module",
|
|
31
|
+
"exports": {
|
|
32
|
+
".": {
|
|
33
|
+
"types": "./index.d.ts",
|
|
34
|
+
"import": "./index.js",
|
|
35
|
+
"default": "./index.js"
|
|
36
|
+
},
|
|
37
|
+
"./lint": {
|
|
38
|
+
"types": "./lint.d.ts",
|
|
39
|
+
"import": "./lint.js",
|
|
40
|
+
"default": "./lint.js"
|
|
41
|
+
},
|
|
42
|
+
"./package.json": "./package.json"
|
|
43
|
+
},
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"@effected/glob": "^0.20.0",
|
|
46
|
+
"@effected/semver": "^0.22.0",
|
|
47
|
+
"@effected/workspaces": "^0.44.1",
|
|
48
|
+
"@effected/yaml": "^0.29.0"
|
|
49
|
+
},
|
|
50
|
+
"peerDependencies": {
|
|
51
|
+
"@effected/markdown": "^0.28.0",
|
|
52
|
+
"@effected/markdown-lint": "^0.1.1",
|
|
53
|
+
"effect": "~4.1.0"
|
|
54
|
+
},
|
|
55
|
+
"peerDependenciesMeta": {
|
|
56
|
+
"@effected/markdown": {
|
|
57
|
+
"optional": true
|
|
58
|
+
},
|
|
59
|
+
"@effected/markdown-lint": {
|
|
60
|
+
"optional": true
|
|
61
|
+
}
|
|
62
|
+
},
|
|
63
|
+
"engines": {
|
|
64
|
+
"node": ">=24.11.0"
|
|
65
|
+
}
|
|
66
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
|
|
2
|
+
// It should be published with your NPM package. It should not be tracked by Git.
|
|
3
|
+
{
|
|
4
|
+
"tsdocVersion": "0.12",
|
|
5
|
+
"toolPackages": [
|
|
6
|
+
{
|
|
7
|
+
"packageName": "@microsoft/api-extractor",
|
|
8
|
+
"packageVersion": "7.60.1"
|
|
9
|
+
}
|
|
10
|
+
]
|
|
11
|
+
}
|