An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): doc namespaces and placed guides need CLI 0.6.4, not 0.7.0 (#6952)
Joeyf261d2f54cfc
diff --git a/.changeset/docs-tree-cli-floor.md b/.changeset/docs-tree-cli-floor.mdnew file mode 100644index 0000000000..c0e9fa5a8f--- /dev/null+++ b/.changeset/docs-tree-cli-floor.md@@ -0,0 +1,9 @@+---+'@astryxdesign/cli': patch+---++[fix] A package with a namespace doc or a placed guide needs `@astryxdesign/cli` 0.6.4, not 0.7.0.++Published 0.6.4 reads an integration's docs tree: it lists the namespace and reads each guide placed in it. 0.6.3 rejects a namespace doc and hides every doc topic the package ships. `integration add doc --parent` wrote `"@astryxdesign/cli": ">=0.7.0"`, a range no released CLI satisfies, and `integration verify` failed a docs-tree package whose CLI peer started at 0.6.4. `integration add doc --parent` now writes `">=0.6.4"`, marked optional, and `integration verify` accepts it. A template that sets `replaces` or `keywords` still needs `">=0.7.0"`.++@josephfarinadiff --git a/.changeset/theme-and-section-id-cli-floor.md b/.changeset/theme-and-section-id-cli-floor.mdindex 9f96ef11b7..3d4b2e25c3 100644--- a/.changeset/theme-and-section-id-cli-floor.md+++ b/.changeset/theme-and-section-id-cli-floor.md@@ -4,6 +4,6 @@[fix] A package that ships a theme or a doc section `id` needs `@astryxdesign/cli` 0.6.4, not 0.7.0.-Published 0.6.4 reads typed theme descriptors and section ids; 0.6.3 rejects both and hides the package's themes or doc topics. The 0.6.5 notes said a stable CLI before 0.7.0 rejects them, so `integration add theme` wrote `"@astryxdesign/cli": ">=0.7.0"`, a range no released CLI satisfies, and `integration verify` failed a theme or section-id package whose CLI peer started at 0.6.4. `integration add theme` now writes `">=0.6.4"`, marked optional, and `integration verify` accepts it for themes and section ids. A namespace doc, a placed guide, and a template that sets `replaces` still need `">=0.7.0"`.+Published 0.6.4 reads typed theme descriptors and section ids; 0.6.3 rejects both and hides the package's themes or doc topics. The 0.6.5 notes said a stable CLI before 0.7.0 rejects them, so `integration add theme` wrote `"@astryxdesign/cli": ">=0.7.0"`, a range no released CLI satisfies, and `integration verify` failed a theme or section-id package whose CLI peer started at 0.6.4. `integration add theme` now writes `">=0.6.4"`, marked optional, and `integration verify` accepts it for themes and section ids. A template that sets `replaces` or `keywords` still needs `">=0.7.0"`.@josephfarinadiff --git a/packages/cli/api/integration/add-contribution.test.mjs b/packages/cli/api/integration/add-contribution.test.mjsindex c8e3003d16..82ce1590dc 100644--- a/packages/cli/api/integration/add-contribution.test.mjs+++ b/packages/cli/api/integration/add-contribution.test.mjs@@ -12,7 +12,7 @@ import {integrationAddTemplate,} from './add-contribution.mjs';import {validateLocalIntegration} from './validate-integration.mjs';-import {DOCS_TREE_CLI} from '../../foundation/integrations/cli-requirement.mjs';+import {NAMESPACE_DOCS_CLI} from '../../foundation/integrations/cli-requirement.mjs';let tmpDir;@@ -355,7 +355,7 @@ describe('integrationAdd doc', () => {// The namespace doc needs a CLI that reads it, declared as an optional peer.const pkg = JSON.parse(fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'));- expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': `>=${DOCS_TREE_CLI}`});+ expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': '>=0.6.4'});expect(pkg.peerDependenciesMeta).toEqual({'@astryxdesign/cli': {optional: true}});const second = await integrationAdd('doc', 'upgrading', {@@ -429,7 +429,7 @@ describe('integrationAdd doc', () => {write('^0.6.0');await integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'acme'});expect(JSON.parse(fs.readFileSync(file, 'utf-8')).peerDependencies).toEqual({- '@astryxdesign/cli': `>=${DOCS_TREE_CLI}`,+ '@astryxdesign/cli': `>=${NAMESPACE_DOCS_CLI}`,});write('^9.1.0');await integrationAdd('doc', 'upgrading', {cwd: tmpDir, parent: 'acme'});diff --git a/packages/cli/api/integration/pack-check.test.mjs b/packages/cli/api/integration/pack-check.test.mjsindex c908ca89da..7be7e3c55d 100644--- a/packages/cli/api/integration/pack-check.test.mjs+++ b/packages/cli/api/integration/pack-check.test.mjs@@ -374,7 +374,10 @@ describe('integrationPackCheck', () => {expect(await codes()).toContain('docs_tree_needs_cli');peer('^0.6.0 || >=0.7.0');expect(await codes()).toContain('docs_tree_needs_cli');- peer('>=0.7.0');+ peer('>=0.6.3');+ expect(await codes()).toContain('docs_tree_needs_cli');+ // Published 0.6.4 reads the docs tree.+ peer('>=0.6.4');expect(await codes()).not.toContain('docs_tree_needs_cli');}, 120_000);@@ -465,6 +468,9 @@ describe('integrationPackCheck', () => {expect(await codes()).toContain('replaces_needs_cli');peer('^0.6.0');expect(await codes()).toContain('replaces_needs_cli');+ // `replaces` still needs 0.7.0.+ peer('>=0.6.4');+ expect(await codes()).toContain('replaces_needs_cli');peer('>=0.7.0');expect(await codes()).not.toContain('replaces_needs_cli');}, 120_000);diff --git a/packages/cli/assets/docs/tree/check-your-docs.doc.mjs b/packages/cli/assets/docs/tree/check-your-docs.doc.mjsindex db05e652e1..3737f4cffa 100644--- a/packages/cli/assets/docs/tree/check-your-docs.doc.mjs+++ b/packages/cli/assets/docs/tree/check-your-docs.doc.mjs@@ -110,7 +110,7 @@ export const docs = {content: [{type: 'prose',- text: '`integration verify` fails a package that ships a docs section or a placed guide without an `@astryxdesign/cli` peer of `>=0.7.0`, or a doc section with an `id` without one of `>=0.6.4`. It does not run the docs check, so run both.',+ text: '`integration verify` fails a package that ships a docs section, a placed guide, or a doc section with an `id` without an `@astryxdesign/cli` peer of `>=0.6.4`. It does not run the docs check, so run both.',},{type: 'code',@@ -120,7 +120,7 @@ export const docs = {{type: 'code',lang: 'text',- code: '- [fail] The package ships a namespace doc or a placed guide but declares no @astryxdesign/cli peer. A stable CLI before 0.7.0 does not read the docs tree, and can hide every doc topic the package ships. Declare "@astryxdesign/cli": ">=0.7.0" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required).',+ code: '- [fail] The package ships a namespace doc or a placed guide but declares no @astryxdesign/cli peer. A stable CLI before 0.6.4 does not read the docs tree, and can hide every doc topic the package ships. Declare "@astryxdesign/cli": ">=0.6.4" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required).',},{type: 'list',diff --git a/packages/cli/assets/docs/tree/checks.doc.mjs b/packages/cli/assets/docs/tree/checks.doc.mjsindex 493787b2ab..97949c4937 100644--- a/packages/cli/assets/docs/tree/checks.doc.mjs+++ b/packages/cli/assets/docs/tree/checks.doc.mjs@@ -106,7 +106,7 @@ export const docs = {'It checks that every contribution file is in the `.tgz` file. A root missing from `files` fails with `Add "templates" to "files" in package.json.`','It lists the components, templates, themes, docs, and codemods the temporary app sees, and compares them with your source.',"It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component, or a default export for a template.",- 'It fails a package that needs an `@astryxdesign/cli` peer and lacks it: `>=0.7.0` for a docs section, a placed guide, or a template `replaces` or `keywords`, and `>=0.6.4` for a doc section with an `id` or a theme.',+ 'It fails a package that needs an `@astryxdesign/cli` peer and lacks it: `>=0.7.0` for a template that sets `replaces` or `keywords`, and `>=0.6.4` for a docs section, a placed guide, a doc section with an `id`, or a theme.',],},{diff --git a/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs b/packages/cli/assets/docs/tree/sections-and-placement.doc.mjsindex ebdaf96ce3..dc9839bb87 100644--- a/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs+++ b/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs@@ -40,7 +40,7 @@ export const docs = {items: ['Edit its `title` and `summary`: readers see them in the docs list and at the top of your section.',"The guide, `docs/deploying.doc.mjs`, gets `placement: {parent: 'namespace:acme', slot: 'guides'}`. Later runs with `--parent acme` reuse the namespace doc.",- '`package.json` gets the optional peer `"@astryxdesign/cli": ">=0.7.0"`, because an older CLI does not read sections; see {@link generic:versioning}.',+ '`package.json` gets the optional peer `"@astryxdesign/cli": ">=0.6.4"`, because an older CLI does not read sections; see {@link generic:versioning}.',],},],diff --git a/packages/cli/assets/docs/tree/troubleshooting.doc.mjs b/packages/cli/assets/docs/tree/troubleshooting.doc.mjsindex 0e1a75eab2..1da491e53d 100644--- a/packages/cli/assets/docs/tree/troubleshooting.doc.mjs+++ b/packages/cli/assets/docs/tree/troubleshooting.doc.mjs@@ -87,15 +87,15 @@ export const docs = {],['`docs_tree_needs_cli`: `The package ships a namespace doc or a placed guide but declares no @astryxdesign/cli peer.`',- "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.7.0'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`.",+ "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.4'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`.",],['`replaces_needs_cli`: The package has a template that sets `replaces` but declares no @astryxdesign/cli peer.',- 'Same fix: an older CLI rejects `replaces`, drops that template, and hides your doc topics.',+ "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.7.0'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`. A stable CLI before 0.7.0 rejects `replaces`, drops that template, and hides your doc topics.",],['`keywords_needs_cli`: The package has a template that sets `keywords` but declares no @astryxdesign/cli peer.',- 'Same fix: an older CLI rejects `keywords`, drops that template, and hides your doc topics.',+ 'The same fix as `replaces_needs_cli`: a stable CLI before 0.7.0 rejects `keywords`, drops that template, and hides your doc topics.',],['`themes_need_cli`: The package ships a theme but declares no @astryxdesign/cli peer.',@@ -139,7 +139,7 @@ export const docs = {],['Your docs section, templates, or themes are missing only in some apps',- 'Those apps run a CLI too old to read them: a stable CLI before 0.7.0 for a docs section or a template that sets `replaces` or `keywords`, or before 0.6.4 for a theme. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm warns about an old CLI.',+ 'Those apps run a CLI too old to read them: a stable CLI before 0.7.0 for a template that sets `replaces` or `keywords`, or before 0.6.4 for a docs section or a theme. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm warns about an old CLI.',],],},diff --git a/packages/cli/assets/docs/tree/versioning.doc.mjs b/packages/cli/assets/docs/tree/versioning.doc.mjsindex 2acb6f237c..c22785f3e6 100644--- a/packages/cli/assets/docs/tree/versioning.doc.mjs+++ b/packages/cli/assets/docs/tree/versioning.doc.mjs@@ -107,14 +107,14 @@ export const docs = {['`@astryxdesign/cli`','You ship a docs section, a placed guide, a template that sets `replaces` or `keywords`, a doc section with an `id`, or a theme',- '`>=0.7.0` for a docs section, a placed guide, `replaces`, or `keywords`; `>=0.6.4` when you ship only a theme or a section `id`. Optional in `peerDependenciesMeta`',+ '`>=0.7.0` when you ship a template that sets `replaces` or `keywords`, otherwise `>=0.6.4`. Optional in `peerDependenciesMeta`',],],},{type: 'code',lang: 'json',- code: '{\n "peerDependencies": {\n "@astryxdesign/core": "^0.6.0",\n "@astryxdesign/cli": ">=0.7.0"\n },\n "peerDependenciesMeta": {\n "@astryxdesign/cli": {"optional": true}\n }\n}',+ code: '{\n "peerDependencies": {\n "@astryxdesign/core": "^0.6.0",\n "@astryxdesign/cli": ">=0.6.4"\n },\n "peerDependenciesMeta": {\n "@astryxdesign/cli": {"optional": true}\n }\n}',},{type: 'prose',@@ -137,8 +137,8 @@ export const docs = {'An unknown field in `astryx.integration.mjs` is ignored with an `unknown_manifest_key` warning, and the rest of the manifest still loads.','A named export that the CLI does not know is ignored with no warning, so `debug` and `gapReport` are safe to add.','A stable CLI before 0.7.0 prints each `{@link ...}` as written.',- 'A stable CLI before 0.7.0 cannot read a docs section or a template that sets `replaces` or `keywords`. It can then hide every doc topic your package ships.',- 'A stable CLI before 0.6.4 cannot read a section `id` or a theme folder that `integration add theme` writes. It can then hide every doc topic your package ships.',+ 'A stable CLI before 0.7.0 rejects a template that sets `replaces` or `keywords`, drops that template, and can hide every doc topic your package ships.',+ 'A stable CLI before 0.6.4 cannot read a docs section, a section `id`, or a theme folder that `integration add theme` writes. It can then hide every doc topic your package ships.','Stable 0.6.3 still loads your components, but 0.6.0 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',],},diff --git a/packages/cli/foundation/integrations/cli-requirement.mjs b/packages/cli/foundation/integrations/cli-requirement.mjsindex bb56d88b3f..88b195a58f 100644--- a/packages/cli/foundation/integrations/cli-requirement.mjs+++ b/packages/cli/foundation/integrations/cli-requirement.mjs@@ -18,13 +18,19 @@ import {semverCompare} from '../env/semver.mjs';export const CLI_PACKAGE = '@astryxdesign/cli';/**- * The first CLI release that reads an integration's docs tree (namespace docs- * and placed guides) and its templates' `replaces` and `keywords`. A release- * before it can hide every doc topic a package with a namespace doc or a- * placed guide ships, with no warning; and it rejects `replaces` or- * `keywords`, drops that template, and hides the package's doc topics.+ * The first stable CLI release that reads an integration's docs tree:+ * namespace docs and placed guides. Published 0.6.3 rejects a namespace doc+ * and hides every doc topic the package ships, with no warning; published+ * 0.6.4 lists the namespace and reads its guides.*/-export const DOCS_TREE_CLI = '0.7.0';+export const NAMESPACE_DOCS_CLI = '0.6.4';++/**+ * The first CLI release that reads a template's `replaces` and `keywords`. A+ * release before it rejects either field, drops that template, and hides the+ * package's doc topics.+ */+export const REPLACES_CLI = '0.7.0';/*** The first stable CLI release that reads typed theme descriptors, the theme@@ -104,16 +110,15 @@ export function lowestAdmitted(range) {* @param {any} pkg package.json* @param {string} feature what the package does, e.g. "ships a namespace doc"* @param {string} loss what an older CLI does with it- * @param {string} [floor] the first stable CLI release that reads it; the- * docs tree's by default, so a caller that names none keeps the strictest- * floor+ * @param {string} floor the first stable CLI release that reads it* @returns {string | null}*/-export function cliRangeProblem(pkg, feature, loss, floor = DOCS_TREE_CLI) {- // A floor that is not a version means the arguments are out of order, as- // after a merge with a caller written for another parameter order. Fail- // loudly rather than compare a range against feature text.- if (lowerVersion(floor) == null) {+export function cliRangeProblem(pkg, feature, loss, floor) {+ // A floor that is missing or not a version means a caller passed the+ // arguments in another order, as after a merge with a caller written for+ // another signature. Fail loudly rather than compare a range against+ // feature text, or against nothing.+ if (typeof floor !== 'string' || lowerVersion(floor) == null) {throw new TypeError(`cliRangeProblem: floor "${floor}" is not a version`);}const range = pkg?.peerDependencies?.[CLI_PACKAGE];@@ -133,7 +138,7 @@ export function cliRangeProblem(pkg, feature, loss, floor = DOCS_TREE_CLI) {* docs on an older CLI, or null when its declared CLI range admits only CLIs* that read the docs tree. Published 0.6.3 hides every topic of a package* with a namespace doc; builds of main before the docs tree also do so for a- * placed guide.+ * placed guide. Published 0.6.4 reads both.* @param {any} pkg package.json* @returns {string | null}*/@@ -142,7 +147,7 @@ export function docsTreeCliProblem(pkg) {pkg,'ships a namespace doc or a placed guide','does not read the docs tree, and can hide every doc topic the package ships',- DOCS_TREE_CLI,+ NAMESPACE_DOCS_CLI,);}@@ -158,7 +163,7 @@ export function replacesCliProblem(pkg) {pkg,'has a template that sets `replaces`',"rejects the field, drops that template, and hides the package's doc topics",- DOCS_TREE_CLI,+ REPLACES_CLI,);}@@ -210,7 +215,7 @@ export function keywordsCliProblem(pkg) {pkg,'has a template that sets `keywords`',"rejects the field, drops that template, and hides the package's doc topics",- DOCS_TREE_CLI,+ REPLACES_CLI,);}@@ -242,5 +247,5 @@ export function withCliPeer(pkg, floor) {* @returns {any}*/export function withDocsTreeCli(pkg) {- return withCliPeer(pkg, DOCS_TREE_CLI);+ return withCliPeer(pkg, NAMESPACE_DOCS_CLI);}diff --git a/packages/cli/foundation/integrations/cli-requirement.test.mjs b/packages/cli/foundation/integrations/cli-requirement.test.mjsindex 8900d75709..5518279809 100644--- a/packages/cli/foundation/integrations/cli-requirement.test.mjs+++ b/packages/cli/foundation/integrations/cli-requirement.test.mjs@@ -3,8 +3,10 @@import fs from 'node:fs';import {describe, expect, it} from 'vitest';import {semverCompare} from '../env/semver.mjs';+import * as requirement from './cli-requirement.mjs';import {- DOCS_TREE_CLI,+ NAMESPACE_DOCS_CLI,+ REPLACES_CLI,SECTION_IDS_CLI,cliRangeProblem,THEMES_CLI,@@ -44,7 +46,7 @@ describe('docsTreeCliProblem', () => {// Stable releases: a canary built from main before its release reports// the older version and reads every feature.expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(- 'A stable CLI before 0.7.0 does not read the docs tree',+ 'A stable CLI before 0.6.4 does not read the docs tree',);});@@ -57,16 +59,19 @@ describe('docsTreeCliProblem', () => {},);- it.each(['>=0.7.0', '^0.7.2', '>=0.7.0 <2'])('accepts %s', range => {- expect(- docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),- ).toBeNull();- });+ it.each(['>=0.6.4', '^0.6.4', '>=0.7.0', '^0.7.2', '>=0.7.0 <2'])(+ 'accepts %s',+ range => {+ expect(+ docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),+ ).toBeNull();+ },+ );it('declares the peer as optional, and keeps what the package says of it', () => {const declared = withDocsTreeCli({name: '@acme/kit'});expect(declared.peerDependencies).toEqual({- '@astryxdesign/cli': `>=${DOCS_TREE_CLI}`,+ '@astryxdesign/cli': '>=0.6.4',});expect(declared.peerDependenciesMeta).toEqual({'@astryxdesign/cli': {optional: true},@@ -94,6 +99,10 @@ describe('replacesCliProblem', () => {expect(replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),).toBeNull();+ // Unlike the docs tree, `replaces` still needs 0.7.0.+ expect(+ replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.6.4'}}),+ ).toContain('admits a stable CLI before 0.7.0');});});@@ -118,11 +127,9 @@ describe('themesCliProblem and sectionIdsCliProblem', () => {}});- it('keeps 0.7.0 for the docs tree, replaces, and keywords', () => {+ it('keeps 0.7.0 for replaces and keywords', () => {const pkg = {peerDependencies: {'@astryxdesign/cli': '>=0.6.4'}};- expect(docsTreeCliProblem(pkg)).toContain(- 'admits a stable CLI before 0.7.0',- );+ expect(docsTreeCliProblem(pkg)).toBeNull();expect(replacesCliProblem(pkg)).toContain('admits a stable CLI before 0.7.0',);@@ -138,7 +145,7 @@ describe('themesCliProblem and sectionIdsCliProblem', () => {const {version} = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'),);- for (const floor of [THEMES_CLI, SECTION_IDS_CLI]) {+ for (const floor of [NAMESPACE_DOCS_CLI, THEMES_CLI, SECTION_IDS_CLI]) {expect(semverCompare(floor, version.split('-')[0])).toBeLessThanOrEqual(0,);@@ -158,10 +165,11 @@ describe('themesCliProblem and sectionIdsCliProblem', () => {});describe('cliRangeProblem', () => {- it('uses the docs-tree floor when a caller names none', () => {- expect(+ it('fails loudly when a caller names no floor', () => {+ expect(() =>+ // @ts-expect-error: the floor is requiredcliRangeProblem({name: '@acme/kit'}, 'ships x', 'drops x'),- ).toContain('A stable CLI before 0.7.0');+ ).toThrow(TypeError);});it('fails loudly when the floor is not a version', () => {@@ -170,3 +178,39 @@ describe('cliRangeProblem', () => {).toThrow(TypeError);});});++describe('every feature check names its CLI floor', () => {+ // The first stable CLI release that reads each feature. A new check, or a+ // check whose floor changes, fails here until this table says so on+ // purpose, so a floor never moves as a side effect of another change.+ const FLOORS = {+ docsTreeCliProblem: '0.6.4',+ replacesCliProblem: REPLACES_CLI,+ keywordsCliProblem: REPLACES_CLI,+ sectionIdsCliProblem: '0.6.4',+ themesCliProblem: '0.6.4',+ };++ it('asks each feature for the CLI release this table names', () => {+ const named = Object.fromEntries(+ Object.entries(requirement)+ .filter(+ ([name, value]) =>+ typeof value === 'function' &&+ /CliProblem$/.test(name) &&+ name !== 'cliRangeProblem',+ )+ .map(([name, check]) => [+ name,+ /A stable CLI before (\d+\.\d+\.\d+)/.exec(+ check({name: '@acme/kit'}) ?? '',+ )?.[1] ?? null,+ ]),+ );+ expect(named).toEqual({+ ...FLOORS,+ replacesCliProblem: '0.7.0',+ keywordsCliProblem: '0.7.0',+ });+ });+});