Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

ci(changesets): check Changeset coverage on pull requests with the release classifier (#7195)

Cindy Zhangd8becc8a204a
diff --git a/.github/scripts/change-scope.cjs b/.github/scripts/change-scope.cjs
index dba1043991..1ac435847b 100644
--- a/.github/scripts/change-scope.cjs
+++ b/.github/scripts/change-scope.cjs
@@ -266,6 +266,7 @@ module.exports = {
classifyChanges,
isKnowledgeRecordPath,
isNodeToolingPath,
+ isPackageReleasePath,
isSpecRecordPath,
parseNameStatus,
};
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 7b335440a3..37cef30a75 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -48,6 +48,30 @@ jobs:
>> "$GITHUB_OUTPUT"
fi
+ # A change that ships to consumers names its package in a Changeset, and a
+ # released CLI JSON id cannot disappear unclassified. The release coverage
+ # audit runs the same classifier over the cut range, so the two agree.
+ - name: Check Changeset coverage
+ if: github.event_name == 'pull_request'
+ env:
+ MERGE_SHA: ${{ github.sha }}
+ run: |
+ set -eu
+ # The checked-out merge commit and its first parent (the base branch
+ # tip): exactly what this pull request lands.
+ git fetch --no-tags --depth=2 origin "$MERGE_SHA"
+ RELEASED=$(git ls-remote --tags --refs origin 'v*' \
+ | sed 's#.*refs/tags/##' \
+ | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+ | sort -V | tail -n 1)
+ if [ -z "$RELEASED" ]; then
+ echo 'No vX.Y.Z release tag found to compare CLI JSON ids against.'
+ exit 1
+ fi
+ git fetch --no-tags --depth=1 origin "+refs/tags/${RELEASED}:refs/tags/${RELEASED}"
+ node scripts/release/changeset-coverage.mjs pr \
+ --base "$MERGE_SHA^1" --head "$MERGE_SHA" --released "$RELEASED"
+
- name: Skip full lint for lightweight docs
if: steps.scope.outputs.docsite_only == 'true' || steps.scope.outputs.spec_only == 'true'
run: echo "Lightweight documentation PR — skipping full lint"
@@ -63,6 +87,13 @@ jobs:
if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true'
run: pnpm check:repo
+ # The CLI README's generated tables (commands, error codes, response
+ # types) ship to consumers. A merge from main can silently drop a
+ # generated row, so the merged result is checked against its sources.
+ - name: Check generated CLI README
+ if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true'
+ run: node packages/cli/scripts/generate-cli-readme.mjs --check
+
- name: Run ESLint
if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true'
run: pnpm lint
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2902c60832..e7e10e2aa7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -674,6 +674,39 @@ pnpm changeset:new --category fix --summary "…" --pr 2717 --contributor yourha
> `minor`; `[experimental]` and every other category must be `patch`), or
> declaring a `major` bump while 0.x.
+#### When CI requires one
+
+Every pull request runs `scripts/release/changeset-coverage.mjs`, the same
+classifier the release coverage audit runs over a release's commits. It fails
+when the pull request changes something a published package ships and no
+Changeset it adds or edits names that package:
+
+- package source, such as `packages/*/src` of a published package;
+- CLI behavior and output under `packages/cli` (`api`, `clients`,
+ `foundation`, `authoring`, `assets`);
+- shipped documentation: `packages/cli/assets/docs`, `*.doc.mjs`, and a
+ package README;
+- consumer-facing `package.json` fields such as `exports`, `bin`, and
+ dependency or peer ranges.
+
+Stories, the sandbox, tests, fixtures, snapshots, spec records, generated
+CHANGELOGs, private and canary-only packages (`lab`, `charts`, `richtext`,
+`vega`), the docsite app, CI, and repository tooling never reach a consumer and
+need no Changeset. The failure names the package and the command to run, for
+example `pnpm changeset:new --packages @astryxdesign/cli --category docs`. Run
+the check locally with
+`node scripts/release/changeset-coverage.mjs pr --base origin/main --explain`.
+
+The same check compares the CLI's machine-readable ids with the latest
+release: response `type` values, response fields, golden JSON fields, and
+`astryx doctor` check ids. Removing or renaming a released one breaks scripts
+that read it. Restore it, or classify the removal in a `@astryxdesign/cli`
+Changeset: a `[breaking]` entry that names the id, or a paragraph beginning
+`Compatibility:` that names the id and says why consumers of the latest
+release keep working. Name an id the way the failure prints it, such as
+`themes` or `DoctorCheck.fix`. Catalog values inside those responses, such as template
+slugs and docs routes, are data and may change.
+
### Version Bumps
- **0.x (current): bump follows the category.** We track standard semver for the `0.x.y` range, where a minor bump is the stable breaking tier (under a caret range like `^0.1.8`, npm resolves `<0.2.0`). A `[breaking]` change bumps the **minor** (`0.x.y → 0.(x+1).0`). A change confined to a surface that was explicitly marked experimental before its first stable publication uses `[experimental]` and bumps the **patch**, even when that experimental API changes incompatibly. Every other category (`feat`, `fix`, `component`, `perf`, `docs`, `chore`) also bumps the patch. If stable defaults, behavior, props, imports, CLI commands, or machine schemas break, the change remains `[breaking]`. `major` is never used while 0.x — it would jump to `1.0.0`. `pnpm changeset:new` writes the right bump from the category you pick; `pnpm check:changesets` enforces the coupling both ways.
diff --git a/scripts/lib/workspace-globs.mjs b/scripts/lib/workspace-globs.mjs
index 81814a4678..73f9386b62 100644
--- a/scripts/lib/workspace-globs.mjs
+++ b/scripts/lib/workspace-globs.mjs
@@ -31,8 +31,18 @@ import path from 'node:path';
*/
export function readWorkspaceGlobs(root) {
const file = path.join(root, 'pnpm-workspace.yaml');
- const src = fs.readFileSync(file, 'utf8');
+ return parseWorkspaceGlobs(fs.readFileSync(file, 'utf8'), file);
+}
+/**
+ * Parse the `packages:` block from pnpm-workspace.yaml source text, for
+ * callers that read the file at a git revision rather than from disk.
+ *
+ * @param {string} src pnpm-workspace.yaml contents.
+ * @param {string} [file] Display name for the error message.
+ * @returns {string[]} Globs exactly as authored, e.g. ['apps/*', 'packages/*'].
+ */
+export function parseWorkspaceGlobs(src, file = 'pnpm-workspace.yaml') {
const globs = [];
let inPackages = false;
diff --git a/scripts/release/active-release.mjs b/scripts/release/active-release.mjs
index 599e4583a3..4a00dd4d8c 100644
--- a/scripts/release/active-release.mjs
+++ b/scripts/release/active-release.mjs
@@ -124,17 +124,28 @@ function validateIdentity(marker, plan) {
return errors;
}
+/**
+ * Does this manifest belong to the stable cut? Private and canary-only
+ * packages publish outside it (or not at all), so their changes never block or
+ * enter a stable release.
+ *
+ * @param {{name?: string, private?: boolean, astryx?: {canaryOnly?: boolean}}} manifest
+ * @returns {boolean}
+ */
+function isStableReleasePackage(manifest) {
+ return (
+ manifest?.name?.startsWith('@astryxdesign/') === true &&
+ manifest.private !== true &&
+ manifest.astryx?.canaryOnly !== true
+ );
+}
+
function publishablePackages(root) {
return expandWorkspaceDirs(root)
.map(dir => path.join(dir, 'package.json'))
.filter(file => fs.existsSync(file))
.map(file => ({file, manifest: readJson(file)}))
- .filter(
- ({manifest}) =>
- manifest.name?.startsWith('@astryxdesign/') &&
- manifest.private !== true &&
- manifest.astryx?.canaryOnly !== true,
- );
+ .filter(({manifest}) => isStableReleasePackage(manifest));
}
function validateReleaseState({
@@ -811,6 +822,7 @@ export {
buildPlan,
canonicalJson,
computePlanDigest,
+ isStableReleasePackage,
listActiveBranches,
validateIdentity,
validateRefMarker,
diff --git a/scripts/release/changeset-coverage.mjs b/scripts/release/changeset-coverage.mjs
new file mode 100644
index 0000000000..084e182277
--- /dev/null
+++ b/scripts/release/changeset-coverage.mjs
@@ -0,0 +1,1001 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Changeset coverage: one classifier for pull requests and releases.
+ *
+ * Pull-request CI and the release coverage audit judge each change through the
+ * same `evaluateChange`, so they cannot disagree about what needed a Changeset.
+ *
+ * 1. Coverage: a changed path that lands in a stable package's tarball (its
+ * `files`, root README, or consumer-facing package.json fields) needs a
+ * Changeset, added or edited by the same change, naming that package. Tests,
+ * stories, spec records, generated CHANGELOGs, unpacked files, private and
+ * canary-only packages, and everything outside a package need none.
+ * 2. Released CLI JSON ids: a response `type`, response field, golden field, or
+ * doctor check id from the latest stable release that is missing at head
+ * breaks scripts (spec:AST-017 FR3, FR13). The change that removes it, or
+ * whose Changeset names it, needs a `[breaking]` Changeset or a
+ * `Compatibility:` note naming its full identity. Catalog values (template
+ * slugs, docs routes) are data and are not compared (FR9, FR11, FR45).
+ *
+ * @input git revisions: a pull request's base and head, or a release range
+ * @output problems naming each package or id and the Changeset that resolves it
+ * @position scripts/release — run by the lint workflow on every pull request
+ * and by the release coverage audit over the cut range
+ */
+
+import {execFileSync} from 'node:child_process';
+import path from 'node:path';
+import {createRequire} from 'node:module';
+import {parseArgs} from 'node:util';
+import {fileURLToPath} from 'node:url';
+import {parseFrontmatter} from '../check-changesets.mjs';
+import {parseWorkspaceGlobs} from '../lib/workspace-globs.mjs';
+import {isStableReleasePackage} from './active-release.mjs';
+
+const require = createRequire(import.meta.url);
+const {parseEntry} = require('../changeset-entry-format.cjs');
+const {
+ isPackageReleasePath,
+ parseNameStatus,
+} = require('../../.github/scripts/change-scope.cjs');
+
+const ROOT = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../..',
+);
+
+export const CLI_PACKAGE = '@astryxdesign/cli';
+const CHANGESET_FILE = /^\.changeset\/(?!README\.md$)[^/]+\.md$/;
+
+/**
+ * package.json fields a consumer's install, import, or tooling reads. A change
+ * to `version` is release bookkeeping, and scripts or devDependencies never
+ * leave the repository, so neither needs a Changeset.
+ */
+export const CONSUMER_MANIFEST_FIELDS = Object.freeze([
+ ...['name', 'type', 'main', 'module', 'types', 'typings', 'exports'],
+ ...['imports', 'bin', 'files', 'sideEffects', 'engines', 'os', 'cpu'],
+ ...['browser', 'style', 'astryx', 'peerDependenciesMeta'],
+ ...['dependencies', 'peerDependencies', 'optionalDependencies'],
+ ...['bundleDependencies', 'bundledDependencies'],
+]);
+
+/** What each shipped surface is called in a failure. */
+const SURFACES = Object.freeze({
+ docs: 'shipped documentation',
+ cli: 'CLI behavior or output',
+ source: 'package source',
+ manifest: 'consumer-facing package.json',
+});
+
+/**
+ * @typedef {object} Tree
+ * @property {string} label revision or name, for messages
+ * @property {(file: string) => string|null} read file contents, or null when absent
+ * @property {(dir: string) => string[]} list every file under `dir`, repo-relative
+ * @property {(files: string[]) => void} [prefetch] read many files in one batch
+ */
+
+function git(root, args) {
+ return execFileSync('git', args, {
+ cwd: root,
+ encoding: 'utf8',
+ maxBuffer: 256 * 1024 * 1024,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+}
+
+/** The repository at `rev`, read through `git cat-file --batch` and cached. */
+export function gitTree(root, rev) {
+ const reads = new Map();
+ const lists = new Map();
+ return {
+ label: rev,
+ read(file) {
+ if (!reads.has(file)) this.prefetch([file]);
+ return reads.get(file);
+ },
+ prefetch(files) {
+ const wanted = files.filter(file => !reads.has(file));
+ if (wanted.length === 0) return;
+ const out = execFileSync('git', ['cat-file', '--batch'], {
+ cwd: root,
+ input: wanted.map(file => `${rev}:${file}`).join('\n') + '\n',
+ maxBuffer: 256 * 1024 * 1024,
+ stdio: ['pipe', 'pipe', 'pipe'],
+ });
+ let offset = 0;
+ for (const file of wanted) {
+ const newline = out.indexOf(10, offset);
+ const header = out.toString('utf8', offset, newline);
+ offset = newline + 1;
+ const m = /^\S+ (\w+) (\d+)$/.exec(header);
+ if (!m) {
+ reads.set(file, null); // "<object> missing"
+ continue;
+ }
+ const size = Number(m[2]);
+ reads.set(
+ file,
+ m[1] === 'blob' ? out.toString('utf8', offset, offset + size) : null,
+ );
+ offset += size + 1;
+ }
+ },
+ list(dir) {
+ if (!lists.has(dir)) {
+ const out = git(root, ['ls-tree', '-r', '--name-only', rev, '--', dir]);
+ lists.set(dir, out.split('\n').filter(Boolean));
+ }
+ return lists.get(dir);
+ },
+ };
+}
+
+/** A tree held in memory, `{path: contents}`, for tests. */
+export function memoryTree(files, label = 'memory') {
+ return {
+ label,
+ read: file => (Object.hasOwn(files, file) ? files[file] : null),
+ list: dir =>
+ Object.keys(files)
+ .filter(file => file.startsWith(`${dir.replace(/\/$/, '')}/`))
+ .sort(),
+ };
+}
+
+function readJson(tree, file) {
+ const contents = tree.read(file);
+ if (contents === null) return null;
+ try {
+ return JSON.parse(contents);
+ } catch {
+ return null;
+ }
+}
+
+function globToRegExp(glob) {
+ const escaped = glob
+ .split('*')
+ .map(part => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+ .join('[^/]*');
+ return new RegExp(`^${escaped}$`);
+}
+
+/** Is repo-relative `dir` a workspace package directory under these globs? */
+export function isWorkspaceDir(dir, globs) {
+ let matched = false;
+ for (const glob of globs) {
+ if (glob.startsWith('!')) {
+ if (globToRegExp(glob.slice(1)).test(dir)) return false;
+ } else if (!glob.includes('**') && globToRegExp(glob).test(dir)) {
+ matched = true;
+ }
+ }
+ return matched;
+}
+
+/** The workspace package that owns `file`: its nearest workspace directory. */
+function owningPackage(tree, file) {
+ const source = tree.read('pnpm-workspace.yaml');
+ if (source === null) return null;
+ const globs = parseWorkspaceGlobs(source);
+ let dir = path.posix.dirname(file);
+ while (dir && dir !== '.') {
+ if (isWorkspaceDir(dir, globs)) {
+ const manifest = readJson(tree, `${dir}/package.json`);
+ return manifest ? {dir, manifest} : null;
+ }
+ dir = path.posix.dirname(dir);
+ }
+ return null;
+}
+
+/**
+ * Is this package released to consumers through the stable cut? Reuses the
+ * release branch's own definition and adds the Changesets ignore list, the
+ * same set `check:changesets` accepts in frontmatter.
+ *
+ * @param {object} manifest
+ * @param {{ignore?: string[]}} config .changeset/config.json
+ * @returns {boolean}
+ */
+export function isCoveredPackage(manifest, config) {
+ return (
+ isStableReleasePackage(manifest) &&
+ !(config?.ignore || []).includes(manifest.name)
+ );
+}
+
+/**
+ * Does `rel` (relative to its package directory) land in the npm tarball?
+ * npm always packs the manifest and the root README; everything else must be
+ * listed in `files`. A package without `files` ships its whole directory, and
+ * a `files` glob this matcher cannot evaluate is treated as shipping
+ * (fail closed).
+ *
+ * @param {object} manifest
+ * @param {string} rel
+ * @returns {boolean}
+ */
+export function isPackedFile(manifest, rel) {
+ if (rel === 'package.json') return true;
+ if (!rel.includes('/') && /^readme(?:\.|$)/i.test(rel)) return true;
+ if (!Array.isArray(manifest.files)) return true;
+ return manifest.files.some(raw => {
+ const entry = String(raw).replace(/^\.\//, '').replace(/\/+$/, '');
+ if (/[*?[\]{}!]/.test(entry)) return true;
+ return rel === entry || rel.startsWith(`${entry}/`);
+ });
+}
+
+function surfaceOf(packageName, rel) {
+ if (rel === 'package.json') return 'manifest';
+ if (
+ /(?:^|\/)readme(?:\.[^/]*)?$/i.test(rel) ||
+ /\.mdx?$/.test(rel) ||
+ /\.doc(?:\.[\w-]+)*\.mjs$/.test(rel) ||
+ (packageName === CLI_PACKAGE && rel.startsWith('assets/docs/'))
+ ) {
+ return 'docs';
+ }
+ return packageName === CLI_PACKAGE ? 'cli' : 'source';
+}
+
+/**
+ * Classify one changed path.
+ *
+ * @param {string} file repo-relative path
+ * @param {{tree: Tree, config: object}} at the tree that holds the path's package
+ * @returns {{ships: true, package: string, surface: string} | {ships: false, reason: string}}
+ */
+export function classifyPath(file, {tree, config}) {
+ const owner = owningPackage(tree, file);
+ if (!owner) return {ships: false, reason: 'outside every workspace package'};
+ const {dir, manifest} = owner;
+ if (!isCoveredPackage(manifest, config)) {
+ return {
+ ships: false,
+ reason: `${manifest.name || dir} is private, canary-only, or not released`,
+ };
+ }
+ const rel = file.slice(dir.length + 1);
+ if (!isPackageReleasePath(file) || /\.spec\.[cm]?[jt]sx?$/.test(rel)) {
+ return {ships: false, reason: 'test, fixture, snapshot, or spec record'};
+ }
+ if (
+ /(?:^|\/)[^/]+\.stories\.[^/]+$/.test(rel) ||
+ /(?:^|\/)stories\//.test(rel)
+ ) {
+ return {ships: false, reason: 'story'};
+ }
+ if (/^changelog\.md$/i.test(rel)) {
+ return {ships: false, reason: 'CHANGELOG generated by the release'};
+ }
+ if (!isPackedFile(manifest, rel)) {
+ return {ships: false, reason: `not in the ${manifest.name} tarball`};
+ }
+ return {
+ ships: true,
+ package: manifest.name,
+ surface: surfaceOf(manifest.name, rel),
+ };
+}
+
+/**
+ * The consumer-facing package.json fields that differ between two manifests.
+ *
+ * @param {object|null} before
+ * @param {object|null} after
+ * @returns {string[]}
+ */
+export function consumerManifestDelta(before, after) {
+ return CONSUMER_MANIFEST_FIELDS.filter(
+ field =>
+ JSON.stringify(lockstepNeutral(before, field)) !==
+ JSON.stringify(lockstepNeutral(after, field)),
+ );
+}
+
+const DEPENDENCY_FIELDS = new Set([
+ 'dependencies',
+ 'peerDependencies',
+ 'optionalDependencies',
+]);
+
+/**
+ * A field's value with fixed-group co-bumps neutralized. The release moves a
+ * fixed group together, rewriting each member's pin on its siblings to the
+ * package's own new version; that version-only co-bump needs no Changeset
+ * (spec:AST-017 FR7). Any other range edit still counts.
+ */
+function lockstepNeutral(manifest, field) {
+ const value = manifest?.[field] ?? null;
+ if (!DEPENDENCY_FIELDS.has(field) || !value || typeof value !== 'object') {
+ return value;
+ }
+ return Object.fromEntries(
+ Object.entries(value).map(([name, range]) => [
+ name,
+ range === manifest.version ? '<own version>' : range,
+ ]),
+ );
+}
+
+/** Packages a set of Changesets names with a real bump. */
+function namedPackages(changesets) {
+ const names = new Set();
+ for (const {text} of changesets) {
+ const fm = parseFrontmatter(text);
+ if (!fm) continue;
+ for (const [name, bump] of Object.entries(fm.releases)) {
+ if (bump !== 'none') names.add(name);
+ }
+ }
+ return names;
+}
+
+/** The Changesets a change adds or edits, read from its head. */
+function changedChangesets(changes, head) {
+ return changes
+ .filter(
+ change =>
+ change.status?.[0] !== 'D' && CHANGESET_FILE.test(change.filename),
+ )
+ .map(change => ({
+ file: change.filename,
+ text: head.read(change.filename) ?? '',
+ }));
+}
+
+/**
+ * Rule 1 for one change (a pull request, or one commit of a release range).
+ *
+ * @param {object} input
+ * @param {Array<{filename: string, previous_filename?: string|null, status?: string|null}>} input.changes
+ * @param {Tree} input.base
+ * @param {Tree} input.head
+ * @param {Set<string>} [input.coveredElsewhere] packages a later fix-up Changeset covers (release audit only)
+ * @returns {{required: Map<string, Map<string, string[]>>, covered: Set<string>, exempt: Array<{file: string, reason: string}>, problems: string[]}}
+ */
+export function checkCoverage({
+ changes,
+ base,
+ head,
+ coveredElsewhere = new Set(),
+}) {
+ const baseConfig = readJson(base, '.changeset/config.json') || {};
+ const headConfig = readJson(head, '.changeset/config.json') || {};
+ /** @type {Map<string, Map<string, string[]>>} package -> surface -> files */
+ const required = new Map();
+ const exempt = [];
+
+ const need = (pkg, surface, file) => {
+ if (!required.has(pkg)) required.set(pkg, new Map());
+ const bySurface = required.get(pkg);
+ if (!bySurface.has(surface)) bySurface.set(surface, []);
+ bySurface.get(surface).push(file);
+ };
+
+ const paths = new Set();
+ for (const change of changes) {
+ paths.add(change.filename);
+ if (change.previous_filename) paths.add(change.previous_filename);
+ }
+
+ // One batched read per tree for everything classification touches: the
+ // workspace layout, every candidate package manifest, and the paths.
+ const wanted = new Set(['pnpm-workspace.yaml', '.changeset/config.json']);
+ for (const file of paths) {
+ wanted.add(file);
+ for (
+ let dir = path.posix.dirname(file);
+ dir && dir !== '.';
+ dir = path.posix.dirname(dir)
+ ) {
+ wanted.add(`${dir}/package.json`);
+ }
+ }
+ base.prefetch?.([...wanted]);
+ head.prefetch?.([...wanted]);
+
+ for (const file of [...paths].sort()) {
+ // A path ships when it ships on either side: a deleted file shipped at
+ // base, and a package leaving the stable cut in this same change cannot
+ // exempt its own shipped edits.
+ const sides = [
+ {tree: head, config: headConfig},
+ {tree: base, config: baseConfig},
+ ].filter(side => side.tree.read(file) !== null);
+ const results = sides.map(side => classifyPath(file, side));
+ const result = results.find(r => r.ships) ??
+ results[0] ?? {ships: false, reason: 'absent on both sides'};
+ if (!result.ships) {
+ exempt.push({file, reason: result.reason});
+ continue;
+ }
+ if (result.surface === 'manifest') {
+ const fields = consumerManifestDelta(
+ readJson(base, file),
+ readJson(head, file),
+ );
+ if (fields.length === 0) {
+ exempt.push({
+ file,
+ reason: 'no consumer-facing package.json field changed',
+ });
+ continue;
+ }
+ need(result.package, 'manifest', `${file} (${fields.join(', ')})`);
+ continue;
+ }
+ need(result.package, result.surface, file);
+ }
+
+ const covered = namedPackages(changedChangesets(changes, head));
+ for (const pkg of coveredElsewhere) covered.add(pkg);
+ const problems = [];
+ for (const [pkg, bySurface] of [...required.entries()].sort()) {
+ if (!covered.has(pkg)) problems.push(coverageProblem(pkg, bySurface));
+ }
+ return {required, covered, exempt, problems};
+}
+
+function coverageProblem(pkg, bySurface) {
+ const lines = [...bySurface].map(([surface, files]) => {
+ const more = files.length > 5 ? `, and ${files.length - 5} more` : '';
+ return ` ${SURFACES[surface]}: ${files.slice(0, 5).join(', ')}${more}`;
+ });
+ const docsOnly = bySurface.size === 1 && bySurface.has('docs');
+ return (
+ `${pkg}: this change ships to consumers without a Changeset naming ${pkg}.\n` +
+ `${lines.join('\n')}\n` +
+ ` Add (or edit) a Changeset naming '${pkg}':\n` +
+ ` pnpm changeset:new --packages ${pkg} --category ${docsOnly ? 'docs' : '<fix|feat>'}\n` +
+ (docsOnly
+ ? ` [docs] fits a change to shipped documentation alone.`
+ : ` Use [fix] for a correction or [feat] for a new capability ` +
+ `(or [docs], [perf], [component], [experimental] when that is what changed).`)
+ );
+}
+
+const RESPONSE_TYPES_DOC =
+ 'packages/cli/foundation/response/response-types.doc.mjs';
+const CLI_DIR = 'packages/cli';
+const GOLDEN_DIR = 'packages/cli/test/__golden__';
+const DOCTOR_DIR = 'packages/cli/api/doctor';
+
+/**
+ * Split a JSDoc `{type}` expression off the front of `text`.
+ *
+ * @returns {{type: string, rest: string}} type without its outer braces
+ */
+function splitTypeExpression(text) {
+ let i = 0;
+ while (i < text.length && /\s/.test(text[i])) i++;
+ if (text[i] !== '{') return {type: '', rest: text.slice(i)};
+ const start = i;
+ let depth = 0;
+ for (; i < text.length; i++) {
+ if (text[i] === '{') depth++;
+ else if (text[i] === '}' && --depth === 0) {
+ i++;
+ break;
+ }
+ }
+ return {
+ type: text.slice(start + 1, i - 1).trim(),
+ rest: text.slice(i).trimStart(),
+ };
+}
+
+/** Split `text` on `separator` where no bracket is open. */
+function splitTopLevel(text, separator) {
+ const parts = [];
+ let depth = 0;
+ let current = '';
+ for (const char of text) {
+ if ('{[(<'.includes(char)) depth++;
+ else if ('}])>'.includes(char)) depth--;
+ if (char === separator && depth === 0) {
+ parts.push(current.trim());
+ current = '';
+ } else {
+ current += char;
+ }
+ }
+ if (current.trim()) parts.push(current.trim());
+ return parts;
+}
+
+/**
+ * What a typedef's own type expression contributes: the typedefs it extends
+ * (`Base & {extra: T}`, or a plain alias) and the keys of inline object parts.
+ */
+function typedefComposition(type) {
+ const bases = [];
+ const keys = [];
+ for (const part of splitTopLevel(type, '&')) {
+ if (
+ /^[A-Za-z_$][\w$]*$/.test(part) &&
+ part !== 'object' &&
+ part !== 'Object'
+ ) {
+ bases.push(part);
+ } else if (part.startsWith('{') && part.endsWith('}')) {
+ for (const member of splitTopLevel(part.slice(1, -1), ',')) {
+ const key = /^['"]?([A-Za-z_$][\w$]*)['"]?\??\s*:/.exec(member)?.[1];
+ if (key) keys.push(key);
+ }
+ }
+ }
+ return {bases, keys};
+}
+
+/**
+ * Every typedef in a `.type.mjs` source: its own `@property` names and what
+ * its type expression composes.
+ *
+ * @param {string} source
+ * @returns {Array<{name: string, fields: string[], bases: string[]}>}
+ */
+export function parseTypedefs(source) {
+ const typedefs = [];
+ for (const [, comment] of source.matchAll(/\/\*\*([\s\S]*?)\*\//g)) {
+ const body = comment.replace(/^[ \t]*\*[ \t]?/gm, '');
+ let current = null;
+ for (const tag of body.split(/\n(?=\s*@)/)) {
+ const m = /^\s*@(typedef|property|prop)\b([\s\S]*)$/.exec(tag);
+ if (!m) continue;
+ const {type, rest} = splitTypeExpression(m[2]);
+ const name =
+ /^\[?\s*([A-Za-z_$][\w$]*(?:(?:\[\])?\.[A-Za-z_$][\w$]*)*)/.exec(
+ rest,
+ )?.[1];
+ if (!name) continue;
+ if (m[1] === 'typedef') {
+ const {bases, keys} = typedefComposition(type);
+ current = {name, fields: [...keys], bases};
+ typedefs.push(current);
+ } else if (current) {
+ current.fields.push(name);
+ }
+ }
+ }
+ return typedefs;
+}
+
+/**
+ * Every field of every typedef, as `Typedef.field`, with fields a typedef
+ * gains by composing another typedef (`A & {extra: T}`) resolved, so moving a
+ * field into a shared base is not a removal.
+ *
+ * @param {string[]} sources every `.type.mjs` source
+ * @returns {string[]}
+ */
+export function typedefFields(...sources) {
+ const byName = new Map();
+ for (const source of sources) {
+ for (const typedef of parseTypedefs(source))
+ byName.set(typedef.name, typedef);
+ }
+ const resolved = new Map();
+ const resolve = (name, seen = new Set()) => {
+ if (resolved.has(name)) return resolved.get(name);
+ const typedef = byName.get(name);
+ if (!typedef || seen.has(name)) return [];
+ seen.add(name);
+ const fields = new Set(typedef.fields);
+ for (const base of typedef.bases) {
+ for (const field of resolve(base, seen)) fields.add(field);
+ }
+ const list = [...fields];
+ resolved.set(name, list);
+ return list;
+ };
+ const out = [];
+ for (const name of byName.keys()) {
+ for (const field of resolve(name)) out.push(`${name}.${field}`);
+ }
+ return out;
+}
+
+/** Every object key path in a golden JSON response, like `data[].topic`. */
+export function jsonKeyPaths(value) {
+ const paths = new Set();
+ (function walk(node, at) {
+ if (Array.isArray(node)) {
+ for (const item of node) walk(item, `${at}[]`);
+ } else if (node && typeof node === 'object') {
+ for (const [key, child] of Object.entries(node)) {
+ const next = at ? `${at}.${key}` : key;
+ paths.add(next);
+ walk(child, next);
+ }
+ }
+ })(value, '');
+ return [...paths];
+}
+
+/**
+ * The machine-readable ids of the CLI's JSON contract in `tree`.
+ * Keyed by a stable string; each carries the full identity a Changeset names
+ * it by (`DoctorCheck.fix`, `docs.list.data[].topic`, `themes`), never a bare
+ * field name that unrelated fields share.
+ *
+ * @param {Tree} tree
+ * @returns {Map<string, {label: string, token: string}>}
+ */
+export function cliJsonIds(tree) {
+ /** @type {Map<string, {label: string, token: string}>} */
+ const ids = new Map();
+
+ const typeFiles = tree
+ .list(CLI_DIR)
+ .filter(file => file.endsWith('.type.mjs'));
+ const goldenFiles = tree
+ .list(GOLDEN_DIR)
+ .filter(file => file.endsWith('.json'));
+ const doctorFiles = tree
+ .list(DOCTOR_DIR)
+ .filter(file => file.endsWith('.mjs'));
+ tree.prefetch?.([
+ RESPONSE_TYPES_DOC,
+ ...typeFiles,
+ ...goldenFiles,
+ ...doctorFiles,
+ ]);
+
+ const responseTypes = tree.read(RESPONSE_TYPES_DOC);
+ if (responseTypes !== null) {
+ for (const [, value] of responseTypes.matchAll(/\bvalue:\s*'([^']+)'/g)) {
+ ids.set(`response-type:${value}`, {
+ label: `response type \`${value}\``,
+ token: value,
+ });
+ }
+ }
+
+ const sourceFile = file =>
+ !file.includes('/node_modules/') &&
+ !/\.(?:test|spec)\.[^/]+$/.test(file) &&
+ isPackageReleasePath(file);
+
+ const typeSources = typeFiles
+ .filter(sourceFile)
+ .map(file => tree.read(file) ?? '');
+ for (const field of typedefFields(...typeSources)) {
+ ids.set(`field:${field}`, {
+ label: `response field \`${field}\``,
+ token: field,
+ });
+ }
+
+ for (const file of goldenFiles) {
+ let golden;
+ try {
+ golden = JSON.parse(tree.read(file) ?? '');
+ } catch {
+ continue;
+ }
+ const name = path.posix.basename(file);
+ const type = typeof golden?.type === 'string' ? golden.type : name;
+ for (const keyPath of jsonKeyPaths(golden)) {
+ ids.set(`golden:${name}:${keyPath}`, {
+ label: `field \`${keyPath}\` of the ${name} golden response`,
+ token: `${type}.${keyPath}`,
+ });
+ }
+ }
+
+ for (const file of doctorFiles) {
+ if (/\.(?:doc|type)\.mjs$/.test(file) || !sourceFile(file)) {
+ continue;
+ }
+ for (const [, , id] of (tree.read(file) ?? '').matchAll(
+ /\bid:\s*(['"])([a-z0-9][a-z0-9-]*)\1/g,
+ )) {
+ ids.set(`doctor-check:${id}`, {
+ label: `doctor check id \`${id}\``,
+ token: id,
+ });
+ }
+ }
+
+ return ids;
+}
+
+const names = (text, token) => text.includes(`\`${token}\``);
+
+/**
+ * Does this Changeset text carry a compatibility note naming `token`? A note
+ * is a paragraph that begins `Compatibility:`.
+ */
+function compatibilityNoteNames(text, token) {
+ return text
+ .split(/\n\s*\n/)
+ .some(
+ paragraph =>
+ /^\s*Compatibility:/i.test(paragraph) && names(paragraph, token),
+ );
+}
+
+/** Pending Changesets in `tree`: file, text, category, and releases. */
+export function pendingChangesets(tree) {
+ const files = tree
+ .list('.changeset')
+ .filter(file => CHANGESET_FILE.test(file));
+ tree.prefetch?.(files);
+ return files.map(file => {
+ const text = tree.read(file) ?? '';
+ const fm = parseFrontmatter(text);
+ return {
+ file,
+ text,
+ category: fm ? parseEntry(fm.summary).category : null,
+ releases: fm ? fm.releases : {},
+ };
+ });
+}
+
+/**
+ * Rule 2. `released` is the latest stable release's ids, `head` the change's
+ * ids. With `base` (a pull request), only ids this change removes, or that a
+ * Changeset it adds or edits describes, are its to classify; without `base`
+ * (a release), every released id missing at head must be classified.
+ *
+ * @param {object} input
+ * @param {Map<string, {label: string, token: string}>} input.released
+ * @param {string} input.releasedLabel
+ * @param {Map<string, {label: string, token: string}>|null} input.base
+ * @param {Map<string, {label: string, token: string}>} input.head
+ * @param {Array<{file: string, text: string}>} input.describedBy Changesets this change adds or edits
+ * @param {ReturnType<typeof pendingChangesets>} input.pending every Changeset at head
+ * @returns {{missing: string[], attributed: string[], problems: string[]}}
+ */
+export function checkReleasedIds({
+ released,
+ releasedLabel,
+ base,
+ head,
+ describedBy,
+ pending,
+}) {
+ const missing = [...released.keys()].filter(key => !head.has(key)).sort();
+ const attributed = missing.filter(key => {
+ if (!base) return true;
+ const {token} = released.get(key);
+ return base.has(key) || describedBy.some(({text}) => names(text, token));
+ });
+
+ const cliChangesets = pending.filter(
+ entry =>
+ entry.releases[CLI_PACKAGE] && entry.releases[CLI_PACKAGE] !== 'none',
+ );
+ const problems = [];
+ for (const key of attributed) {
+ const {label, token} = released.get(key);
+ const classified = cliChangesets.some(
+ entry =>
+ (entry.category === 'breaking' && names(entry.text, token)) ||
+ compatibilityNoteNames(entry.text, token),
+ );
+ if (classified) continue;
+ problems.push(
+ `${CLI_PACKAGE}: ${label} is in the released ${releasedLabel} JSON contract and is missing at this head.\n` +
+ ` Scripts read released JSON ids, so removing or renaming one is incompatible\n` +
+ ` (spec:AST-017 FR3, FR13). Restore \`${token}\`, or classify the removal in a\n` +
+ ` Changeset naming '${CLI_PACKAGE}':\n` +
+ ` - a [breaking] Changeset whose text names \`${token}\` (admitted only once a minor\n` +
+ ` is scheduled; see check:changesets), or\n` +
+ ` - a paragraph beginning "Compatibility:" that names \`${token}\` and says why a\n` +
+ ` consumer of ${releasedLabel} keeps working.`,
+ );
+ }
+ return {missing, attributed, problems};
+}
+
+/**
+ * @param {object} input
+ * @param {ReturnType<typeof parseNameStatus>} input.changes
+ * @param {Tree} input.base
+ * @param {Tree} input.head
+ * @param {Tree|null} input.released latest stable release, or null to skip rule 2
+ * @param {boolean} [input.attributeToChange] false at release time: every missing id counts
+ * @param {Set<string>} [input.coveredElsewhere] see checkCoverage
+ */
+export function evaluateChange({
+ changes,
+ base,
+ head,
+ released,
+ attributeToChange = true,
+ coveredElsewhere,
+}) {
+ const coverage = checkCoverage({changes, base, head, coveredElsewhere});
+ let ids = {missing: [], attributed: [], problems: []};
+ if (released) {
+ ids = checkReleasedIds({
+ released: cliJsonIds(released),
+ releasedLabel: released.label,
+ base: attributeToChange ? cliJsonIds(base) : null,
+ head: cliJsonIds(head),
+ describedBy: changedChangesets(changes, head),
+ pending: pendingChangesets(head),
+ });
+ }
+ return {coverage, ids, problems: [...coverage.problems, ...ids.problems]};
+}
+
+/**
+ * Packages that pending Changesets cover for an already-merged pull request:
+ * a fix-up Changeset that names the package and cites the pull request
+ * (`#1234`), as the release process asks for a change that merged without
+ * one.
+ *
+ * @param {ReturnType<typeof pendingChangesets>} pending
+ * @param {string|null} prNumber
+ * @returns {Set<string>}
+ */
+export function fixupCoverage(pending, prNumber) {
+ const covered = new Set();
+ if (!prNumber) return covered;
+ const cites = new RegExp(`#${prNumber}(?!\\d)`);
+ for (const entry of pending) {
+ if (!cites.test(entry.text)) continue;
+ for (const [name, bump] of Object.entries(entry.releases)) {
+ if (bump !== 'none') covered.add(name);
+ }
+ }
+ return covered;
+}
+
+/** The newest stable `vX.Y.Z` tag: the release the check compares against. */
+export function newestStableTag(root) {
+ return (
+ git(root, ['tag', '--list', 'v*', '--sort=-v:refname'])
+ .split('\n')
+ .find(tag => /^v\d+\.\d+\.\d+$/.test(tag)) ?? null
+ );
+}
+
+function diffChanges(root, from, to) {
+ return parseNameStatus(git(root, ['diff', '--name-status', '-M', from, to]));
+}
+
+/** Print each problem (and with --explain, every classification); 1 on problems. */
+function report(entries, explain) {
+ for (const {label, result} of explain ? entries : []) {
+ console.log(`\n${label}`);
+ for (const [pkg, bySurface] of result.coverage.required) {
+ for (const [surface, files] of bySurface) {
+ for (const file of files)
+ console.log(` ships ${pkg} (${surface}): ${file}`);
+ }
+ }
+ for (const {file, reason} of result.coverage.exempt) {
+ console.log(` exempt ${file} — ${reason}`);
+ }
+ }
+ const failing = entries.filter(entry => entry.result.problems.length);
+ if (failing.length === 0) return 0;
+ console.error('\n✗ Changeset coverage found problems:\n');
+ for (const {label, result} of failing) {
+ for (const problem of result.problems)
+ console.error(` - ${label}\n ${problem}`);
+ }
+ console.error('\nSee "When CI requires one" in CONTRIBUTING.md.\n');
+ return 1;
+}
+
+function main(argv) {
+ const {positionals, values} = parseArgs({
+ args: argv,
+ allowPositionals: true,
+ options: {
+ root: {type: 'string', default: ROOT},
+ released: {type: 'string'},
+ base: {type: 'string'},
+ head: {type: 'string', default: 'HEAD'},
+ since: {type: 'string'},
+ until: {type: 'string', default: 'origin/main'},
+ explain: {type: 'boolean', default: false},
+ },
+ });
+ const [mode] = positionals;
+ const root = path.resolve(values.root);
+ const releasedRef = values.released ?? newestStableTag(root);
+ const released = releasedRef ? gitTree(root, releasedRef) : null;
+ if (!released || released.read('package.json') === null) {
+ console.error(
+ 'No vX.Y.Z release is available to compare CLI JSON ids against. Fetch ' +
+ "release tags (git fetch origin 'refs/tags/v*:refs/tags/v*') or pass --released <ref>.",
+ );
+ return 2;
+ }
+
+ if (mode === 'pr' && values.base) {
+ const mergeBase = git(root, [
+ 'merge-base',
+ values.base,
+ values.head,
+ ]).trim();
+ const result = evaluateChange({
+ changes: diffChanges(root, mergeBase, values.head),
+ base: gitTree(root, mergeBase),
+ head: gitTree(root, values.head),
+ released,
+ });
+ const code = report(
+ [{label: `${mergeBase.slice(0, 12)}..${values.head}`, result}],
+ values.explain,
+ );
+ if (code === 0) {
+ const pkgs = [...result.coverage.required.keys()];
+ console.log(
+ `✓ Changeset coverage — ${pkgs.length ? `ships to ${pkgs.join(', ')}, each named` : 'nothing here ships to consumers'}; ` +
+ `released CLI JSON ids checked against ${releasedRef}`,
+ );
+ }
+ return code;
+ }
+
+ if (mode === 'release') {
+ // Every commit in the range, judged exactly as its pull request was, plus
+ // the fix-up Changesets the release process adds for a commit that merged
+ // without one. Released ids are judged once, at the end of the range.
+ const since = values.since ?? releasedRef;
+ const until = values.until;
+ const pending = pendingChangesets(gitTree(root, until));
+ const commits = git(root, [
+ 'rev-list',
+ '--reverse',
+ '--no-merges',
+ `${since}..${until}`,
+ ])
+ .split('\n')
+ .filter(Boolean);
+ const entries = commits.map(sha => {
+ const subject = git(root, ['log', '-1', '--format=%s', sha]).trim();
+ const pr = /\(#(\d+)\)\s*$/.exec(subject)?.[1] ?? null;
+ const result = evaluateChange({
+ changes: diffChanges(root, `${sha}^`, sha),
+ base: gitTree(root, `${sha}^`),
+ head: gitTree(root, sha),
+ released: null,
+ coveredElsewhere: fixupCoverage(pending, pr),
+ });
+ return {label: `${sha.slice(0, 10)} ${subject}`, result};
+ });
+ const end = gitTree(root, until);
+ entries.push({
+ label: `${until}: released CLI JSON ids`,
+ result: evaluateChange({
+ changes: [],
+ base: end,
+ head: end,
+ released,
+ attributeToChange: false,
+ }),
+ });
+ console.log(
+ `range: ${since}..${until} (${commits.length} commits); CLI JSON ids against ${releasedRef}`,
+ );
+ const code = report(entries, values.explain);
+ if (code === 0)
+ console.log('✓ every shipped change in the range names its package');
+ return code;
+ }
+
+ console.error(
+ 'usage: changeset-coverage.mjs pr --base <ref> [--head <ref>] [--released <ref>] [--explain]\n' +
+ ' changeset-coverage.mjs release [--since <tag>] [--until <ref>] [--released <ref>] [--explain]',
+ );
+ return 2;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+ process.exitCode = main(process.argv.slice(2));
+}
diff --git a/scripts/release/changeset-coverage.test.mjs b/scripts/release/changeset-coverage.test.mjs
new file mode 100644
index 0000000000..b56d538933
--- /dev/null
+++ b/scripts/release/changeset-coverage.test.mjs
@@ -0,0 +1,818 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Changeset coverage regression tests.
+ *
+ * @input in-memory repository trees shaped like the real workspace
+ * @output proofs that a shipped change needs a Changeset naming its package,
+ * that exempt surfaces need none, and that a released CLI JSON id cannot
+ * disappear unclassified — including red arms replaying #7125 and #7154
+ * @position focused suite for scripts/release/changeset-coverage.mjs
+ */
+
+import fs from 'node:fs';
+import {describe, expect, it} from 'vitest';
+import {
+ classifyPath,
+ cliJsonIds,
+ consumerManifestDelta,
+ evaluateChange,
+ fixupCoverage,
+ pendingChangesets,
+ isPackedFile,
+ isWorkspaceDir,
+ jsonKeyPaths,
+ memoryTree,
+ typedefFields,
+} from './changeset-coverage.mjs';
+
+const WORKSPACE = `packages:
+ - 'apps/*'
+ - '!apps/example-*'
+ - 'packages/*'
+ - 'packages/themes/*'
+ - 'internal/*'
+`;
+
+const CONFIG = JSON.stringify({
+ fixed: [
+ ['@astryxdesign/cli', '@astryxdesign/core', '@astryxdesign/theme-stone'],
+ ],
+ ignore: ['@astryxdesign/storybook', '@astryxdesign/sandbox'],
+});
+
+const manifest = (name, extra = {}) =>
+ JSON.stringify({name, version: '0.6.6', ...extra});
+
+const CLI_FILES = [
+ 'clients',
+ 'api',
+ 'assets',
+ 'authoring',
+ 'foundation',
+ 'scripts/postinstall.mjs',
+ 'CHANGELOG.md',
+];
+
+const DOCTOR_RELEASED = `export const checks = [
+ {id: 'node-version', label: 'Node'},
+ {id: 'themes', label: 'Themes'},
+];
+`;
+const DOCTOR_WITHOUT_THEMES = `export const checks = [
+ {id: 'node-version', label: 'Node'},
+];
+`;
+const THEME_CHECKS = `export const themeChecks = [{id: 'theme-management', label: 'Theme management'}];
+`;
+
+const RESPONSE_TYPES = `export const doc = {
+ members: [
+ {value: 'doctor', description: 'Doctor checks.'},
+ {value: 'docs.list', description: 'Doc topics.'},
+ ],
+};
+`;
+
+const DOCTOR_TYPES = `/**
+ * @typedef {object} DoctorCheck
+ * @property {string} id - Stable machine-readable id.
+ * @property {string} label
+ * @property {string} [fix] - Remediation.
+ */
+
+/**
+ * @typedef {object} DoctorResponse
+ * @property {'doctor'} type
+ * @property {{checks: DoctorCheck[], summary: {pass: number}}} data
+ */
+`;
+
+const DOCS_LIST_GOLDEN = JSON.stringify({
+ apiVersion: 1,
+ type: 'docs.list',
+ data: [
+ {topic: 'layout', description: 'Layout.', package: '@astryxdesign/cli'},
+ ],
+});
+
+/** A small repository with the real package layout. */
+function repo(overrides = {}) {
+ const files = {
+ 'pnpm-workspace.yaml': WORKSPACE,
+ 'package.json': manifest('astryx-root', {private: true}),
+ '.changeset/config.json': CONFIG,
+ '.changeset/README.md': '# Changesets\n',
+ 'packages/cli/package.json': manifest('@astryxdesign/cli', {
+ files: CLI_FILES,
+ bin: {astryx: './clients/cli/bin/astryx.mjs'},
+ }),
+ 'packages/cli/README.md': '# CLI\n',
+ 'packages/cli/assets/docs/layout.doc.mjs':
+ 'export default {title: "Layout"};\n',
+ 'packages/cli/api/doctor/doctor.mjs': DOCTOR_RELEASED,
+ 'packages/cli/api/doctor/doctor.type.mjs': DOCTOR_TYPES,
+ 'packages/cli/api/doctor/doctor.test.mjs': "it('x', () => {});\n",
+ 'packages/cli/foundation/response/response-types.doc.mjs': RESPONSE_TYPES,
+ 'packages/cli/test/__golden__/docs-list.json': DOCS_LIST_GOLDEN,
+ 'packages/cli/scripts/generate.mjs': '// repo-only generator\n',
+ 'packages/core/package.json': manifest('@astryxdesign/core', {
+ files: ['dist', 'src', 'README.md', 'CHANGELOG.md'],
+ peerDependencies: {react: '^19.0.0'},
+ }),
+ 'packages/core/src/Button/Button.tsx': 'export const Button = 1;\n',
+ 'packages/core/src/Button/Button.doc.mjs': 'export const doc = {};\n',
+ 'packages/core/src/Button/Button.test.tsx': 'test();\n',
+ 'packages/core/src/Button/Button.a11y.chromium.spec.ts': 'test();\n',
+ 'packages/core/src/Button/Button.stories.tsx': 'export default {};\n',
+ 'packages/core/src/Button/Button.spec.md': '# Button spec\n',
+ 'packages/core/src/Button/__fixtures__/data.ts': 'export {};\n',
+ 'packages/core/CHANGELOG.md': '# Changelog\n',
+ 'packages/themes/stone/package.json': manifest(
+ '@astryxdesign/theme-stone',
+ {files: ['dist', 'src']},
+ ),
+ 'packages/themes/stone/src/stoneTheme.ts': 'export const stone = {};\n',
+ 'packages/lab/package.json': manifest('@astryxdesign/lab', {
+ private: true,
+ files: ['src'],
+ }),
+ 'packages/lab/src/Thing.tsx': 'export {};\n',
+ 'packages/charts/package.json': manifest('@astryxdesign/charts', {
+ private: true,
+ astryx: {canaryOnly: true},
+ files: ['src'],
+ }),
+ 'packages/charts/src/Chart.tsx': 'export {};\n',
+ 'apps/storybook/package.json': manifest('@astryxdesign/storybook', {
+ private: true,
+ }),
+ 'apps/storybook/stories/Button.stories.tsx': 'export default {};\n',
+ 'apps/sandbox/package.json': manifest('@astryxdesign/sandbox', {
+ private: true,
+ }),
+ 'apps/sandbox/src/App.tsx': 'export {};\n',
+ 'apps/docsite/package.json': manifest('docsite', {private: true}),
+ 'apps/docsite/pages/index.tsx': 'export {};\n',
+ '.github/workflows/lint.yml': 'name: Lint\n',
+ 'scripts/check-changesets.mjs': '// tooling\n',
+ 'docs/specs/AST-017/spec.md': '# spec\n',
+ ...overrides,
+ };
+ for (const [file, contents] of Object.entries(files)) {
+ if (contents === null) delete files[file];
+ }
+ return files;
+}
+
+const changeset = (packages, body) =>
+ `---\n${Object.entries(packages)
+ .map(([name, bump]) => `'${name}': ${bump}`)
+ .join('\n')}\n---\n\n${body}\n\n@contributor\n`;
+
+/** Build the change between two in-memory trees, git name-status style. */
+function change(baseFiles, headFiles, {released = baseFiles} = {}) {
+ const changes = [];
+ for (const file of new Set([
+ ...Object.keys(baseFiles),
+ ...Object.keys(headFiles),
+ ])) {
+ const before = baseFiles[file];
+ const after = headFiles[file];
+ if (before === after) continue;
+ const status = before === undefined ? 'A' : after === undefined ? 'D' : 'M';
+ changes.push({filename: file, previous_filename: null, status});
+ }
+ return evaluateChange({
+ changes,
+ base: memoryTree(baseFiles, 'base'),
+ head: memoryTree(headFiles, 'head'),
+ released: released ? memoryTree(released, 'v0.6.6') : null,
+ });
+}
+
+const at = files => ({
+ tree: memoryTree(files),
+ config: JSON.parse(files['.changeset/config.json']),
+});
+
+describe('classifyPath — what ships to consumers', () => {
+ const files = repo();
+ it.each([
+ ['packages/core/src/Button/Button.tsx', '@astryxdesign/core', 'source'],
+ ['packages/core/src/Button/Button.doc.mjs', '@astryxdesign/core', 'docs'],
+ ['packages/cli/api/doctor/doctor.mjs', '@astryxdesign/cli', 'cli'],
+ ['packages/cli/assets/docs/layout.doc.mjs', '@astryxdesign/cli', 'docs'],
+ ['packages/cli/README.md', '@astryxdesign/cli', 'docs'],
+ [
+ 'packages/themes/stone/src/stoneTheme.ts',
+ '@astryxdesign/theme-stone',
+ 'source',
+ ],
+ ])('%s ships in %s as %s', (file, pkg, surface) => {
+ expect(classifyPath(file, at(files))).toEqual({
+ ships: true,
+ package: pkg,
+ surface,
+ });
+ });
+
+ it.each([
+ ['packages/core/src/Button/Button.test.tsx', /test/],
+ ['packages/core/src/Button/Button.a11y.chromium.spec.ts', /test/],
+ ['packages/core/src/Button/Button.stories.tsx', /story/],
+ ['packages/core/src/Button/Button.spec.md', /spec record/],
+ ['packages/core/src/Button/__fixtures__/data.ts', /fixture/],
+ ['packages/cli/api/doctor/doctor.test.mjs', /test/],
+ ['packages/cli/test/__golden__/docs-list.json', /test/],
+ ['packages/core/CHANGELOG.md', /CHANGELOG/],
+ ['packages/cli/scripts/generate.mjs', /tarball/],
+ ['packages/lab/src/Thing.tsx', /private/],
+ ['packages/charts/src/Chart.tsx', /canary-only/],
+ ['apps/storybook/stories/Button.stories.tsx', /private/],
+ ['apps/sandbox/src/App.tsx', /private/],
+ ['apps/docsite/pages/index.tsx', /private/],
+ ['.github/workflows/lint.yml', /outside/],
+ ['scripts/check-changesets.mjs', /outside/],
+ ['docs/specs/AST-017/spec.md', /outside/],
+ ])('%s is exempt', (file, reason) => {
+ const result = classifyPath(file, at(files));
+ expect(result.ships).toBe(false);
+ expect(result.reason).toMatch(reason);
+ });
+
+ it('treats a Changesets-ignored package as exempt even when it is not private', () => {
+ const ignored = repo({
+ 'apps/sandbox/package.json': manifest('@astryxdesign/sandbox'),
+ });
+ expect(classifyPath('apps/sandbox/src/App.tsx', at(ignored)).ships).toBe(
+ false,
+ );
+ });
+});
+
+describe('isPackedFile, isWorkspaceDir, consumerManifestDelta', () => {
+ it('follows npm packing: manifest, root README, and files entries', () => {
+ const m = {files: ['src', 'scripts/postinstall.mjs']};
+ expect(isPackedFile(m, 'package.json')).toBe(true);
+ expect(isPackedFile(m, 'README.md')).toBe(true);
+ expect(isPackedFile(m, 'src/a/b.ts')).toBe(true);
+ expect(isPackedFile(m, 'scripts/postinstall.mjs')).toBe(true);
+ expect(isPackedFile(m, 'scripts/other.mjs')).toBe(false);
+ expect(isPackedFile(m, 'srcs/x.ts')).toBe(false);
+ expect(isPackedFile({}, 'anything.ts')).toBe(true);
+ expect(isPackedFile({files: ['dist/*.js']}, 'other.ts')).toBe(true);
+ });
+
+ it('matches pnpm workspace globs, honoring exclusions', () => {
+ const globs = [
+ 'apps/*',
+ '!apps/example-*',
+ 'packages/*',
+ 'packages/themes/*',
+ ];
+ expect(isWorkspaceDir('packages/core', globs)).toBe(true);
+ expect(isWorkspaceDir('packages/themes/stone', globs)).toBe(true);
+ expect(isWorkspaceDir('apps/example-next', globs)).toBe(false);
+ expect(isWorkspaceDir('packages/core/src', globs)).toBe(false);
+ });
+
+ it('reports only consumer-facing manifest fields', () => {
+ expect(
+ consumerManifestDelta(
+ {version: '1', scripts: {a: 'x'}},
+ {version: '2', scripts: {a: 'y'}},
+ ),
+ ).toEqual([]);
+ expect(
+ consumerManifestDelta(
+ {peerDependencies: {react: '^18'}},
+ {peerDependencies: {react: '^19'}},
+ ),
+ ).toEqual(['peerDependencies']);
+ });
+
+ it('ignores a fixed-group co-bump of a sibling pin, but not a real range edit', () => {
+ const before = {
+ version: '0.6.5',
+ peerDependencies: {'@astryxdesign/core': '0.6.5', react: '>=19'},
+ };
+ const synced = {
+ version: '0.6.6',
+ peerDependencies: {'@astryxdesign/core': '0.6.6', react: '>=19'},
+ };
+ expect(consumerManifestDelta(before, synced)).toEqual([]);
+ const loosened = {
+ version: '0.6.5',
+ peerDependencies: {'@astryxdesign/core': '^0.6.0', react: '>=19'},
+ };
+ expect(consumerManifestDelta(before, loosened)).toEqual([
+ 'peerDependencies',
+ ]);
+ });
+});
+
+describe('rule 1 — a shipped change names its package', () => {
+ it('passes when a Changeset in the change names the package', () => {
+ const base = repo();
+ const head = repo({
+ 'packages/core/src/Button/Button.tsx': 'export const Button = 2;\n',
+ '.changeset/button.md': changeset(
+ {'@astryxdesign/core': 'patch'},
+ '[fix] Button renders.',
+ ),
+ });
+ expect(change(base, head).problems).toEqual([]);
+ });
+
+ it('fails a source change whose Changeset names a different package', () => {
+ const base = repo();
+ const head = repo({
+ 'packages/core/src/Button/Button.tsx': 'export const Button = 2;\n',
+ '.changeset/button.md': changeset(
+ {'@astryxdesign/cli': 'patch'},
+ '[fix] Wrong package.',
+ ),
+ });
+ const [problem, ...rest] = change(base, head).problems;
+ expect(rest).toEqual([]);
+ expect(problem).toContain(
+ '@astryxdesign/core: this change ships to consumers without a Changeset naming @astryxdesign/core',
+ );
+ expect(problem).toContain(
+ 'package source: packages/core/src/Button/Button.tsx',
+ );
+ expect(problem).toContain(
+ 'pnpm changeset:new --packages @astryxdesign/core --category <fix|feat>',
+ );
+ });
+
+ it('does not count a Changeset that only names the package with bump none', () => {
+ const base = repo();
+ const head = repo({
+ 'packages/core/src/Button/Button.tsx': 'export const Button = 2;\n',
+ '.changeset/button.md': changeset(
+ {'@astryxdesign/core': 'none'},
+ '[fix] Nothing.',
+ ),
+ });
+ expect(change(base, head).problems).toHaveLength(1);
+ });
+
+ it('accepts an edit to an existing pending Changeset that names the package', () => {
+ const base = repo({
+ '.changeset/button.md': changeset(
+ {'@astryxdesign/core': 'patch'},
+ '[fix] Button.',
+ ),
+ });
+ const head = repo({
+ 'packages/core/src/Button/Button.tsx': 'export const Button = 2;\n',
+ '.changeset/button.md': changeset(
+ {'@astryxdesign/core': 'patch'},
+ '[fix] Button, again.',
+ ),
+ });
+ expect(change(base, head).problems).toEqual([]);
+ });
+
+ it('does not let an untouched pending Changeset cover a new change', () => {
+ const pending = {
+ '.changeset/button.md': changeset(
+ {'@astryxdesign/core': 'patch'},
+ '[fix] Button.',
+ ),
+ };
+ const base = repo(pending);
+ const head = repo({
+ ...pending,
+ 'packages/core/src/Button/Button.tsx': 'export const Button = 2;\n',
+ });
+ expect(change(base, head).problems).toHaveLength(1);
+ });
+
+ it('names every uncovered package once, with its own surfaces', () => {
+ const base = repo();
+ const head = repo({
+ 'packages/core/src/Button/Button.tsx': 'export const Button = 2;\n',
+ 'packages/themes/stone/src/stoneTheme.ts':
+ 'export const stone = {a: 1};\n',
+ });
+ const problems = change(base, head).problems;
+ expect(problems).toHaveLength(2);
+ expect(problems[0]).toMatch(/^@astryxdesign\/core:/);
+ expect(problems[1]).toMatch(/^@astryxdesign\/theme-stone:/);
+ });
+
+ it('does not let a package leaving the stable cut exempt its own shipped edits', () => {
+ const base = repo();
+ const head = repo({
+ 'packages/themes/stone/package.json': manifest(
+ '@astryxdesign/theme-stone',
+ {private: true, files: ['dist', 'src']},
+ ),
+ 'packages/themes/stone/src/stoneTheme.ts':
+ 'export const stone = {a: 1};\n',
+ });
+ const problems = change(base, head).problems;
+ expect(problems).toHaveLength(1);
+ expect(problems[0]).toContain(
+ 'package source: packages/themes/stone/src/stoneTheme.ts',
+ );
+ });
+
+ it('counts a deleted shipped file', () => {
+ const base = repo();
+ const head = repo({'packages/core/src/Button/Button.doc.mjs': null});
+ expect(change(base, head).problems[0]).toContain(
+ 'shipped documentation: packages/core/src/Button/Button.doc.mjs',
+ );
+ });
+
+ it('counts a peer range change but not a version or script change', () => {
+ const base = repo();
+ const bumped = repo({
+ 'packages/core/package.json': manifest('@astryxdesign/core', {
+ version: '0.6.7',
+ files: ['dist', 'src', 'README.md', 'CHANGELOG.md'],
+ peerDependencies: {react: '^19.0.0'},
+ scripts: {build: 'x'},
+ }),
+ });
+ expect(change(base, bumped).problems).toEqual([]);
+ const narrowed = repo({
+ 'packages/core/package.json': manifest('@astryxdesign/core', {
+ files: ['dist', 'src', 'README.md', 'CHANGELOG.md'],
+ peerDependencies: {react: '^19.1.0'},
+ }),
+ });
+ expect(change(base, narrowed).problems[0]).toContain(
+ 'consumer-facing package.json: packages/core/package.json (peerDependencies)',
+ );
+ });
+
+ it('needs nothing for stories, sandbox, tests, lab, canary-only, docsite, CI, tooling, specs, or CHANGELOGs', () => {
+ const base = repo();
+ const head = repo({
+ 'apps/storybook/stories/Button.stories.tsx':
+ 'export default {title: "B"};\n',
+ 'apps/sandbox/src/App.tsx': 'export const x = 1;\n',
+ 'apps/docsite/pages/index.tsx': 'export const y = 1;\n',
+ 'packages/core/src/Button/Button.test.tsx': 'test(2);\n',
+ 'packages/core/src/Button/Button.spec.md': '# Button spec v2\n',
+ 'packages/core/src/Button/__fixtures__/data.ts': 'export const d = 1;\n',
+ 'packages/core/CHANGELOG.md': '# Changelog\n\n## 0.6.7\n',
+ 'packages/cli/test/__golden__/docs-list.json': DOCS_LIST_GOLDEN.replace(
+ 'Layout.',
+ 'Layouts.',
+ ),
+ 'packages/cli/scripts/generate.mjs': '// changed generator\n',
+ 'packages/lab/src/Thing.tsx': 'export const t = 1;\n',
+ 'packages/charts/src/Chart.tsx': 'export const c = 1;\n',
+ '.github/workflows/lint.yml': 'name: Lint 2\n',
+ 'scripts/check-changesets.mjs': '// tooling 2\n',
+ 'docs/specs/AST-017/spec.md': '# spec 2\n',
+ });
+ const result = change(base, head);
+ expect(result.problems).toEqual([]);
+ expect(result.coverage.required.size).toBe(0);
+ });
+});
+
+describe('red arm — #7125: shipped CLI docs changed without a Changeset', () => {
+ // #7125 split the Layout doc into a namespace: it rewrote
+ // packages/cli/assets/docs/*.doc.mjs (shipped in the CLI tarball and read by
+ // `astryx docs`), updated tests and the docs-list golden, and added no
+ // Changeset. The release coverage audit treated `/docs/` as exempt, so the
+ // change would have shipped with no release note.
+ const base = repo();
+ const head = repo({
+ 'packages/cli/assets/docs/layout.doc.mjs':
+ 'export default {title: "Layout", children: ["layout/scaffold"]};\n',
+ 'packages/cli/assets/docs/tree/scaffold.doc.mjs':
+ 'export default {title: "Scaffold"};\n',
+ 'packages/cli/assets/docs/tree/side-panels.doc.mjs':
+ 'export default {title: "Side panels"};\n',
+ 'packages/cli/api/doctor/doctor.test.mjs': "it('y', () => {});\n",
+ 'packages/cli/test/__golden__/docs-list.json': JSON.stringify({
+ apiVersion: 1,
+ type: 'docs.list',
+ data: [
+ {
+ topic: 'layout/scaffold',
+ description: 'Scaffold.',
+ package: '@astryxdesign/cli',
+ },
+ ],
+ }),
+ });
+
+ it('fails, naming @astryxdesign/cli and a [docs] Changeset', () => {
+ const {problems} = change(base, head);
+ expect(problems).toHaveLength(1);
+ expect(problems[0]).toContain(
+ '@astryxdesign/cli: this change ships to consumers without a Changeset naming @astryxdesign/cli',
+ );
+ expect(problems[0]).toContain(
+ 'shipped documentation: packages/cli/assets/docs/layout.doc.mjs',
+ );
+ expect(problems[0]).toContain(
+ 'pnpm changeset:new --packages @astryxdesign/cli --category docs',
+ );
+ });
+
+ it('does not treat the renamed docs route in the golden as a broken JSON id (FR45)', () => {
+ expect(change(base, head).ids.problems).toEqual([]);
+ });
+
+ it('at release time, accepts a later fix-up Changeset that names the package and cites the pull request', () => {
+ const fixup = changeset(
+ {'@astryxdesign/cli': 'patch'},
+ '[docs] Layout lists its focused guides.\n\n(#7125)',
+ );
+ const pending = pendingChangesets(
+ memoryTree({...head, '.changeset/layout-docs-namespace.md': fixup}),
+ );
+ expect([...fixupCoverage(pending, '7125')]).toEqual(['@astryxdesign/cli']);
+ expect(fixupCoverage(pending, '712')).toEqual(new Set());
+ const result = evaluateChange({
+ changes: [
+ {filename: 'packages/cli/assets/docs/layout.doc.mjs', status: 'M'},
+ ],
+ base: memoryTree(base),
+ head: memoryTree(head),
+ released: null,
+ coveredElsewhere: fixupCoverage(pending, '7125'),
+ });
+ expect(result.problems).toEqual([]);
+ });
+
+ it('passes once a [docs] Changeset names @astryxdesign/cli', () => {
+ const fixed = {
+ ...head,
+ '.changeset/layout-namespace.md': changeset(
+ {'@astryxdesign/cli': 'patch'},
+ '[docs] Layout is now a namespace of focused guides.',
+ ),
+ };
+ expect(change(base, fixed).problems).toEqual([]);
+ });
+});
+
+describe('red arm — #7154: a released doctor check id described as a [fix] rename', () => {
+ // v0.6.6 reports a doctor check with id `themes`. Main dropped it, and
+ // #7154 added a [fix] Changeset saying "`themes` check is now
+ // `theme-management`" — an incompatible rename of a released JSON id,
+ // classified as a patch.
+ const released = repo();
+ const base = repo({
+ 'packages/cli/api/doctor/doctor.mjs': DOCTOR_WITHOUT_THEMES,
+ 'packages/cli/api/doctor/theme-checks.mjs': THEME_CHECKS,
+ });
+ const head = {
+ ...base,
+ 'packages/cli/api/theme/_adapter.mjs': 'export const pkg = 1;\n',
+ '.changeset/theme-import-names-package.md': changeset(
+ {'@astryxdesign/cli': 'patch'},
+ "[fix] `astryx theme add <slug> --import` names the npm package that owns the added theme.\n\n`astryx doctor`'s `themes` check is now `theme-management`, with focused `theme-*` checks beside it.",
+ ),
+ };
+
+ it('fails, naming the id and both ways to classify it', () => {
+ const {problems, coverage} = change(base, head, {released});
+ expect(coverage.problems).toEqual([]);
+ expect(problems).toHaveLength(1);
+ expect(problems[0]).toContain(
+ '@astryxdesign/cli: doctor check id `themes` is in the released v0.6.6 JSON contract and is missing at this head.',
+ );
+ expect(problems[0]).toContain(
+ 'a [breaking] Changeset whose text names `themes`',
+ );
+ expect(problems[0]).toContain(
+ 'a paragraph beginning "Compatibility:" that names `themes`',
+ );
+ });
+
+ it('also fails the change that removed the id', () => {
+ const removal = {
+ ...base,
+ '.changeset/app-themes.md': changeset(
+ {'@astryxdesign/cli': 'patch'},
+ '[feat] Apps can import package-managed themes.',
+ ),
+ };
+ const {problems} = change(released, removal, {released});
+ expect(problems).toHaveLength(1);
+ expect(problems[0]).toContain('doctor check id `themes`');
+ });
+
+ it('passes when the id is restored', () => {
+ const restored = {
+ ...head,
+ 'packages/cli/api/doctor/theme-checks.mjs': `${THEME_CHECKS}export const legacy = {id: 'themes'};\n`,
+ };
+ expect(change(base, restored, {released}).problems).toEqual([]);
+ });
+
+ it('passes with a compatibility note naming the id', () => {
+ const noted = {
+ ...head,
+ '.changeset/theme-import-names-package.md': changeset(
+ {'@astryxdesign/cli': 'patch'},
+ '[fix] Theme import names its package.\n\nCompatibility: `themes` was never documented as stable in this release line, so no released consumer reads it.',
+ ),
+ };
+ expect(change(base, noted, {released}).problems).toEqual([]);
+ });
+
+ it('passes with a [breaking] Changeset naming the id', () => {
+ const breaking = {
+ ...head,
+ '.changeset/doctor-themes-renamed.md': changeset(
+ {'@astryxdesign/cli': 'minor'},
+ "[breaking] `astryx doctor`'s `themes` check is now `theme-management`.",
+ ),
+ };
+ expect(change(base, breaking, {released}).problems).toEqual([]);
+ });
+
+ it('does not accept a [breaking] Changeset that never names the id', () => {
+ const vague = {
+ ...head,
+ '.changeset/doctor-themes-renamed.md': changeset(
+ {'@astryxdesign/cli': 'minor'},
+ '[breaking] Doctor checks were reorganized.',
+ ),
+ };
+ expect(change(base, vague, {released}).problems).toHaveLength(1);
+ });
+
+ it('leaves an unrelated change alone', () => {
+ const unrelated = {
+ ...base,
+ 'packages/core/src/Button/Button.tsx': 'export const Button = 3;\n',
+ '.changeset/button.md': changeset(
+ {'@astryxdesign/core': 'patch'},
+ '[fix] Button renders.',
+ ),
+ };
+ expect(change(base, unrelated, {released}).problems).toEqual([]);
+ });
+
+ it('at release time, reports every released id missing at the end of the range', () => {
+ const result = evaluateChange({
+ changes: [],
+ base: memoryTree(base, 'origin/main'),
+ head: memoryTree(base, 'origin/main'),
+ released: memoryTree(released, 'v0.6.6'),
+ attributeToChange: false,
+ });
+ expect(result.ids.problems).toHaveLength(1);
+ expect(result.ids.problems[0]).toContain('doctor check id `themes`');
+ });
+});
+
+describe('rule 2 — the released CLI JSON contract', () => {
+ it('reads response types, typedef fields, golden fields, and doctor ids', () => {
+ const ids = [...cliJsonIds(memoryTree(repo())).keys()];
+ expect(ids).toEqual(
+ expect.arrayContaining([
+ 'response-type:doctor',
+ 'response-type:docs.list',
+ 'field:DoctorCheck.id',
+ 'field:DoctorCheck.fix',
+ 'field:DoctorResponse.data',
+ 'golden:docs-list.json:data[].topic',
+ 'doctor-check:node-version',
+ 'doctor-check:themes',
+ ]),
+ );
+ expect(ids.some(id => id.includes('doctor.test'))).toBe(false);
+ });
+
+ it('flags a removed response field and a removed response type', () => {
+ const base = repo();
+ const head = repo({
+ 'packages/cli/api/doctor/doctor.type.mjs': DOCTOR_TYPES.replace(
+ ' * @property {string} [fix] - Remediation.\n',
+ '',
+ ),
+ 'packages/cli/foundation/response/response-types.doc.mjs':
+ RESPONSE_TYPES.replace(
+ " {value: 'docs.list', description: 'Doc topics.'},\n",
+ '',
+ ),
+ '.changeset/x.md': changeset(
+ {'@astryxdesign/cli': 'patch'},
+ '[fix] Tidy.',
+ ),
+ });
+ const problems = change(base, head).ids.problems.join('\n');
+ expect(problems).toContain('response field `DoctorCheck.fix`');
+ expect(problems).toContain('response type `docs.list`');
+ });
+
+ it('clears a removed field only by its full identity, not a shared field name', () => {
+ const base = repo();
+ const removed = DOCTOR_TYPES.replace(
+ ' * @property {string} [fix] - Remediation.\n',
+ '',
+ );
+ const byName = repo({
+ 'packages/cli/api/doctor/doctor.type.mjs': removed,
+ '.changeset/x.md': changeset(
+ {'@astryxdesign/cli': 'minor'},
+ '[breaking] Drop `fix`.',
+ ),
+ });
+ expect(change(base, byName).ids.problems).toHaveLength(1);
+ const byIdentity = repo({
+ 'packages/cli/api/doctor/doctor.type.mjs': removed,
+ '.changeset/x.md': changeset(
+ {'@astryxdesign/cli': 'minor'},
+ '[breaking] Drop `DoctorCheck.fix`.',
+ ),
+ });
+ expect(change(base, byIdentity).problems).toEqual([]);
+ });
+
+ it('does not count moving fields into a composed typedef as a removal', () => {
+ const released = repo({
+ 'packages/cli/api/docs/docs.type.mjs':
+ '/**\n * @typedef {object} DocsIndexSection\n * @property {string} id\n * @property {string} title\n */\n',
+ });
+ const head = repo({
+ 'packages/cli/api/docs/docs.type.mjs':
+ '/**\n * @typedef {object} DocsIndexEntry\n * @property {string} id\n * @property {string} title\n */\n\n' +
+ '/**\n * @typedef {DocsIndexEntry & {package: string}} DocsIndexSection\n */\n',
+ '.changeset/x.md': changeset(
+ {'@astryxdesign/cli': 'patch'},
+ '[feat] Sections name their `package`.',
+ ),
+ });
+ expect(change(released, head).problems).toEqual([]);
+ });
+
+ it('ignores an id that was never released (FR2)', () => {
+ const released = repo();
+ const base = repo({
+ 'packages/cli/api/doctor/theme-checks.mjs': THEME_CHECKS,
+ });
+ const head = repo({
+ '.changeset/x.md': changeset(
+ {'@astryxdesign/cli': 'patch'},
+ '[fix] Drop the unreleased `theme-management` check.',
+ ),
+ });
+ expect(change(base, head, {released}).problems).toEqual([]);
+ });
+});
+
+describe('parsers', () => {
+ it('reads typedef fields through nested type braces and optional names', () => {
+ expect(typedefFields(DOCTOR_TYPES)).toEqual([
+ 'DoctorCheck.id',
+ 'DoctorCheck.label',
+ 'DoctorCheck.fix',
+ 'DoctorResponse.type',
+ 'DoctorResponse.data',
+ ]);
+ expect(
+ typedefFields(
+ '/**\n * @typedef {object} R\n * @property {object} data\n * @property {string[]} data.items\n */',
+ ),
+ ).toEqual(['R.data', 'R.data.items']);
+ expect(
+ typedefFields(
+ "/**\n * @typedef {object} Base\n * @property {import('@astryxdesign/cli/authoring').Block[]} [content]\n */",
+ "/**\n * @typedef {Base & {package: string, 'kind'?: string}} Child\n */",
+ ).sort(),
+ ).toEqual(['Base.content', 'Child.content', 'Child.kind', 'Child.package']);
+ });
+
+ it('collects key paths, not values', () => {
+ expect(jsonKeyPaths({type: 'x', data: [{a: 1, b: {c: 2}}]})).toEqual([
+ 'type',
+ 'data',
+ 'data[].a',
+ 'data[].b',
+ 'data[].b.c',
+ ]);
+ });
+});
+
+describe('lint workflow', () => {
+ it('runs the Changeset coverage and generated CLI README checks on pull requests', () => {
+ const workflow = fs.readFileSync(
+ new URL('../../.github/workflows/lint.yml', import.meta.url),
+ 'utf8',
+ );
+ expect(workflow).toMatch(/^ {2}pull_request:/m);
+ expect(workflow).toContain(
+ 'node scripts/release/changeset-coverage.mjs pr',
+ );
+ expect(workflow).toContain(
+ 'node packages/cli/scripts/generate-cli-readme.mjs --check',
+ );
+ });
+});