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.cjsindex 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.ymlindex 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 docsif: 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 ESLintif: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true'run: pnpm lintdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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',+ );+ });+});