An open source design system that's fully customizable and agent ready
TypeScript
docs: document integration authoring end to end (#6290)
Joey98a2e4eb7e08
diff --git a/packages/cli/api/upgrade/upgrade.doc.mjs b/packages/cli/api/upgrade/upgrade.doc.mjsindex c78f5d12a3..46ec76a0e3 100644--- a/packages/cli/api/upgrade/upgrade.doc.mjs+++ b/packages/cli/api/upgrade/upgrade.doc.mjs@@ -16,8 +16,9 @@ export const doc = {description:'Migrates project source from a previous Astryx version to the currently ' +'installed one by running the registered codemods, and compares the fully ' +- 'rendered managed agent-docs block on every path, including same-Core ' +- 'integration guidance changes. Dry-run previews without writing; `apply` ' ++ 'rendered managed agent-docs block on every migration path, including ' ++ 'same-Core integration guidance changes; list and registry-only modes do not ' ++ 'run migration reconciliation. Dry-run previews without writing; `apply` ' +'writes the prepared block only after selected codemods and hooks succeed. ' +'Core codemods run before ' +'the config is loaded so a config codemod can repair an otherwise-invalid ' +@@ -68,7 +69,7 @@ export const doc = {name: 'options.integration',type: 'string[]',description:- 'Explicit integration package names / file paths to process.',+ 'Explicit integration specifiers to process. Resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.',},{name: 'options.path',diff --git a/packages/cli/api/upgrade/upgrade.type.mjs b/packages/cli/api/upgrade/upgrade.type.mjsindex 0c659c7718..befab23989 100644--- a/packages/cli/api/upgrade/upgrade.type.mjs+++ b/packages/cli/api/upgrade/upgrade.type.mjs@@ -135,7 +135,7 @@* @property {boolean} [force] Run codemods even if `from` >= installed.* @property {string} [codemod] Run a single named transform.* @property {string[]} [skipCodemod] Exclude named codemods (re-run past a failure).- * @property {string[]} [integration] Explicit integration package names / file paths.+ * @property {string[]} [integration] Explicit integration specifiers resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.* @property {string} [path] Source directory to scan (default `./src`).* @property {boolean} [installDeps] Auto-install jscodeshift without prompting.* @property {boolean} [registry] Reconcile only ShadCN-copied compositions; `from` is not required.diff --git a/packages/cli/assets/docs/cli-integrations.doc.mjs b/packages/cli/assets/docs/cli-integrations.doc.mjsindex 2a59c077a3..7fcb3716ee 100644--- a/packages/cli/assets/docs/cli-integrations.doc.mjs+++ b/packages/cli/assets/docs/cli-integrations.doc.mjs@@ -20,7 +20,7 @@ export const docs = {},{type: 'prose',- text: 'The authoring CLI owns the integration file. The first `astryx integration add` creates `astryx.integration.mjs`; each later add declares its root only after writing a valid contribution behind it. Identity (name and version) still comes from package.json. For the consumer side, run `npx astryx docs getting-started`.',+ text: 'The authoring CLI owns the integration file. The first `astryx integration add` creates `astryx.integration.mjs`; each later add declares its root only after writing a valid contribution behind it. Identity (name and version) still comes from package.json. For the consumer side, run `astryx docs getting-started`.',},{type: 'prose',@@ -52,7 +52,7 @@ export const docs = {content: [{type: 'prose',- text: 'Do not start by hand-editing a manifest. Add the contribution you mean to ship; Astryx creates the manifest, writes every required file, preserves an existing custom root, and updates an existing package.json files allowlist without creating one.',+ text: 'Do not start by hand-editing a manifest. Add the contribution you mean to ship; Astryx creates the manifest, writes every required file, preserves an existing custom root, and updates an existing package.json files allowlist without creating one. Always run these commands from the locally installed CLI in the package (e.g. `node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs` or `pnpm astryx`), not `npx @astryxdesign/cli` — npx may resolve a stale registry version whose integration scaffolding does not match the installed one.',},{type: 'code',@@ -84,17 +84,17 @@ export const docs = {content: [{type: 'prose',- text: 'A useful theme package usually ships more than colors. Start with the source theme, then add the guides its consumers need. Each command writes a complete contribution and keeps the package manifest in sync.',+ text: 'A useful theme package usually ships more than colors. Start with the source theme, author the palette request at `themes/ocean/palette.config.json`, then add the guides its consumers need. The `integration add` commands keep the package manifest in sync; add palette outputs to the theme catalog after generation.',},{type: 'code',lang: 'bash',label: 'In the provider package',- code: 'astryx integration add theme ocean\nastryx theme palette generate palette.config.json --out themes/ocean/tokens/ocean.palette.ts\nastryx integration add doc brand-theme\nastryx integration add doc theme-migration\nastryx theme list --package @acme/brand-integration\nastryx docs brand-theme\nastryx integration pack --check\nnpm pack',+ code: 'astryx integration add theme ocean\nastryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts\nastryx integration add doc brand-theme\nastryx integration add doc theme-migration\nastryx theme list --package @acme/brand-integration\nastryx docs brand-theme\nastryx integration pack --check\nnpm pack',},{type: 'prose',- text: 'Edit the generated theme and guide files before publishing. Palette generation writes an importable TypeScript candidate and a reproducibility receipt; import the candidate from the theme and list both nested files in that theme catalog entry. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source file or files allowlist entry fails before a consumer sees it.',+ text: "Edit the generated theme and guide files before publishing. The shown palette command writes `themes/ocean/tokens/ocean.palette.ts` and its sibling `themes/ocean/tokens/ocean.palette.receipt.json`. The TypeScript candidate directly exports `black`, `white`, and `palette`; import what the theme uses from `./tokens/ocean.palette`. Keep the request at `themes/ocean/palette.config.json`, and list the theme source, request, candidate, and receipt in the catalog entry's `files` array. Add any optional wrapper, refs, icon, or preview modules only when you author them, and list each one too. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source file or files allowlist entry fails before a consumer sees it.",},{type: 'code',@@ -108,6 +108,25 @@ export const docs = {},],},+ {+ title: 'Contribution Kinds at a Glance',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'Each contribution kind uses a different metadata suffix, type stamp, and discovery rule. The table below prevents the most common first-time authoring mistake — using the wrong file or export convention.',+ },+ {+ type: 'code',+ lang: 'text',+ code: "Kind Metadata suffix type stamp Source file\n──────── ───────────────────────── ───────────── ──────────────────────\nComponent Name.doc.{ts,mjs,js} 'component' Name.tsx (same stem)\nTemplate Name.template.{ts,mjs,js} 'page'/'block' Name.tsx (same stem)\nDoc topic topic.doc.{ts,mjs,js} 'generic' (none — docs are prose)\nCodemod <version>/<id>.{ts,mjs,js} 'code'/'config' (the codemod IS the source)\nTheme manifest.json entry — <slug>/<entry>.ts",+ },+ {+ type: 'prose',+ text: 'The `type` stamp is how new docs should be authored — it routes parsing to the correct schema at the load boundary. Legacy docs without a stamp still load via shape-sniffing for backward compatibility, but unstamped docs rely on heuristics (presence of `props`, `params`, etc.) and may parse under the wrong schema if the shape is ambiguous. Always stamp new integration contributions.',+ },+ ],+ },{title: 'The Integration File',category: 'guide',@@ -133,7 +152,7 @@ export const docs = {content: [{type: 'prose',- text: 'Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`.',+ text: "Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`. The doc file must default-export an object with `type: 'component'` — not `'generic'` (that is for reference docs) and not `'page'`/`'block'` (those are for templates).",},{type: 'prose',@@ -142,7 +161,7 @@ export const docs = {{type: 'code',lang: 'typescript',- code: "// AcmeCarousel.doc.ts\nexport default {\n type: 'component',\n name: 'AcmeCarousel',\n description: 'A carousel that cycles through slides.',\n // props, usage, examples, ...\n};",+ code: "// AcmeCarousel.doc.ts\nexport default {\n type: 'component',\n name: 'AcmeCarousel',\n description: 'A carousel that cycles through slides.',\n // props, usage, examples, ...\n} satisfies import('@astryxdesign/cli/authoring').ComponentDoc;",},],},@@ -152,7 +171,7 @@ export const docs = {content: [{type: 'prose',- text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a plain object stamped with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`.",+ text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a plain object with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) as its default export in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`. Do not use the `.doc.{ts,mjs,js}` suffix — that is for component docs and reference docs.",},{type: 'prose',@@ -165,7 +184,7 @@ export const docs = {},{type: 'prose',- text: 'The CLI needs both files at consume time. `integration add` includes the templates root when package.json already has a files allowlist. It never creates an exports map, because doing that can make previously-open deep imports private; when a map already exists, it adds the generated source subpath without replacing author-owned entries. `integration pack --check` proves the source and metadata survive the tarball and verifies every component through the public import its metadata advertises.',+ text: 'The CLI needs both files at consume time. `integration add` includes the templates root when package.json already has a files allowlist. It never creates an exports map, because doing that can make previously-open deep imports private; when a map already exists, it adds the generated source subpath without replacing author-owned entries. Use consumer-safe extensionless subpaths in the exports map (e.g. `"./templates/AcmeDashboard"` instead of `"./templates/AcmeDashboard.tsx"`), so consumers import without knowing the file extension. `integration pack --check` proves the source and metadata survive the tarball and verifies every component through the public import its metadata advertises.',},],},@@ -175,7 +194,7 @@ export const docs = {content: [{type: 'prose',- text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'`, the same shape core's own topics use.",+ text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object with `type: 'generic'` as its default export — not `'component'` (that is for component docs with a same-stem source file). This is the same shape core's own topics use.",},{type: 'code',@@ -219,16 +238,33 @@ export const docs = {{type: 'code',lang: 'text',- code: 'themes/\n manifest.json\n ocean/\n oceanTheme.ts',+ code: 'themes/\n manifest.json\n ocean/\n oceanTheme.ts\n palette.config.json\n tokens/\n ocean.palette.ts\n ocean.palette.receipt.json',},{type: 'prose',- text: "The root catalog uses the same entry contract as Astryx's bundled themes: `slug`, `displayName`, `description`, `maintained`, `entry`, `exportName`, and `files`. `entry` and every file are relative to `themes/<slug>/`; `exportName` identifies a named runtime export in the entry source. Astryx parses that source without executing it, requires every local static import and re-export to name a file in `files`, and rejects missing or type-only exports.",+ text: 'The root catalog `manifest.json` must be `{ "version": 1, "themes": [...] }`. Each entry in the `themes` array requires every field shown below — omitting any one is a hard validation error:',+ },+ {+ type: 'list',+ style: 'unordered',+ items: [+ '`slug` — lowercase kebab-case starting with a letter (e.g. `"ocean"`). Must be unique within the catalog.',+ '`displayName` — human-readable label (e.g. `"Ocean"`).',+ '`description` — string description of the theme.',+ '`maintained` — boolean indicating active maintenance.',+ '`entry` — source file relative to `themes/<slug>/` (e.g. `"oceanTheme.ts"`).',+ '`exportName` — a valid JS identifier naming the runtime export in the entry file (e.g. `"oceanTheme"`). Astryx parses the source without executing it and rejects missing or type-only exports.',+ '`files` — non-empty array of filenames relative to `themes/<slug>/`. Must include the entry file and every local static import the entry source uses. Astryx validates that every listed file exists on disk and that every local import in the entry names a file in this list.',+ ],},{type: 'code',lang: 'json',- code: '{\n "version": 1,\n "themes": [{\n "slug": "ocean",\n "displayName": "Ocean",\n "description": "Ocean theme.",\n "maintained": true,\n "entry": "oceanTheme.ts",\n "exportName": "oceanTheme",\n "files": ["oceanTheme.ts"]\n }]\n}',+ code: '{\n "version": 1,\n "themes": [{\n "slug": "ocean",\n "displayName": "Ocean",\n "description": "Ocean theme with OKLCH palettes.",\n "maintained": true,\n "entry": "oceanTheme.ts",\n "exportName": "oceanTheme",\n "files": [\n "oceanTheme.ts",\n "palette.config.json",\n "tokens/ocean.palette.ts",\n "tokens/ocean.palette.receipt.json"\n ]\n }]\n}',+ },+ {+ type: 'prose',+ text: 'The generated candidate is already importable: it exports `black`, `white`, `palette`, and a default palette value. Import it directly from `./tokens/ocean.palette`. A wrapper or palette-refs module is optional application code, not generator output; list it only if you create it.',},{type: 'prose',@@ -271,10 +307,32 @@ export const docs = {type: 'prose',text: "Ship codemods so `astryx upgrade` can migrate consumers across breaking changes in your package. Point the integration file's `codemods` field at your codemods root, and author each one as a plain object stamped with `type: 'code'` (transforms source files) or `type: 'config'` (rewrites the consumer's `astryx.config`).",},+ {+ type: 'prose',+ text: 'The codemods root uses a version-folder-first layout. Each folder name is an exact semver string (no `v` prefix) matching the version the codemod migrates TO. Each module under it is a kebab-case `.ts`, `.mjs`, or `.js` file whose default export is the codemod envelope:',+ },+ {+ type: 'code',+ lang: 'text',+ code: 'codemods/\n 0.2.0/\n rename-widget-prop.ts\n 0.3.0/\n update-theme-import.ts\n config/rename-integration.ts',+ },+ {+ type: 'prose',+ text: 'Codemod ids (the extension-less relative path under the version folder, e.g. `rename-widget-prop`, `config/rename-integration`) must be unique within a package across all versions. A duplicate id across versions is a hard error.',+ },{type: 'code',lang: 'typescript',- code: "// codemods/v2-rename-prop.ts\nexport default {\n type: 'code',\n // title, description, transform, ...\n};",+ code: "// codemods/0.2.0/rename-widget-prop.ts\nexport default {\n type: 'code',\n title: 'Rename AcmeWidget oldProp to newProp',\n description: 'Updates JSX props in consumer source files.',\n transform(file, api) {\n // jscodeshift transform\n return file.source;\n },\n};",+ },+ {+ type: 'prose',+ text: "`astryx upgrade` is dry-run by default — it previews which codemods would run and what files would change, without writing anything. Pass `--apply` to write the changes. There is no `--dry-run` flag; omitting `--apply` is the dry run. The `--integration` flag resolves each value beneath the project's `node_modules` (for example, `--integration @acme/widgets`). Absolute paths and `.` or `..` segments are rejected; other slash-separated values remain beneath `node_modules`.",+ },+ {+ type: 'code',+ lang: 'bash',+ code: '# Preview what would change (dry-run, the default)\nastryx upgrade --from 0.1.0\n\n# Apply the migration\nastryx upgrade --from 0.1.0 --apply',},{type: 'prose',diff --git a/packages/cli/authoring/integration/type.ts b/packages/cli/authoring/integration/type.tsindex a3b1a70394..573a589add 100644--- a/packages/cli/authoring/integration/type.ts+++ b/packages/cli/authoring/integration/type.ts@@ -21,7 +21,13 @@ export interface AstryxIntegration {components?: string;/** Relative path to the templates root (resolved to absolute). */templates?: string;- /** Relative path to the codemods root (resolved to absolute). */+ /** Relative path to the codemods root (resolved to absolute).+ * The root uses a version-folder-first layout:+ * `<codemodsRoot>/<version>/<id>.<ext>`, where `<version>` is an exact+ * semver string (e.g. `0.2.0`, no `v` prefix) and `<id>` is a kebab-case+ * module basename. Each module default-exports a codemod envelope stamped+ * `type: 'code'` or `type: 'config'`. Codemod ids must be unique within+ * a package across all versions. */codemods?: string;/** Relative path to the reference-docs (topics) root (resolved to* absolute). Every `{topic}.doc.{ts,mjs,js}` under it is a topic the CLI@@ -29,7 +35,14 @@ export interface AstryxIntegration {* `replace` or `extend` a built-in topic; see the ReferenceDoc type. */docs?: string;/** Relative path to the source-theme catalog root (resolved to absolute).- * The root contains `manifest.json` plus one directory per theme slug. */+ * The root contains `manifest.json` plus one directory per theme slug.+ * `manifest.json` is `{ "version": 1, "themes": [...] }` where each+ * entry requires `slug`, `displayName`, `description` (string),+ * `maintained` (boolean), `entry` (source file relative to `themes/<slug>/`),+ * `exportName` (a valid JS identifier naming the runtime export), and+ * `files` (non-empty array of filenames relative to `themes/<slug>/`).+ * Every file listed must exist on disk; the entry file must also appear+ * in `files`. */themes?: string;/** Static package guidance appended to the CLI-owned managed agent block. */agentDocs?: {diff --git a/packages/cli/clients/cli/commands/theme-palette-generate.doc.mjs b/packages/cli/clients/cli/commands/theme-palette-generate.doc.mjsindex 62157f6da5..ec492a1dcb 100644--- a/packages/cli/clients/cli/commands/theme-palette-generate.doc.mjs+++ b/packages/cli/clients/cli/commands/theme-palette-generate.doc.mjs@@ -18,7 +18,11 @@ export const doc = {'Without --out it prints a preview. With --out it writes a candidate file and detached ' +'receipt. --preview writes a standardized, self-contained HTML review artifact. ' +'TypeScript output is directly importable and contains no generator dependency. ' +- 'JSON is also supported. Existing author-owned files are left untouched unless --overwrite is explicit.',+ 'JSON is also supported. Existing author-owned files are left untouched unless --overwrite is explicit. ' ++ 'When used in a theme integration, keep the palette request under the theme slug, ' ++ 'write the candidate and receipt under that same slug, import the candidate from the theme source, ' ++ "and list all three paths in the theme catalog entry's `files` array " ++ 'so `astryx theme add` copies them into the consumer project.',fn: 'themePaletteGenerate',args: [{name: 'config', param: 'configPath', required: true}],options: [@@ -42,15 +46,15 @@ export const doc = {examples: [{label: 'Preview candidate JSON',- cli: 'astryx theme palette generate palette.config.json',+ cli: 'astryx theme palette generate themes/ocean/palette.config.json',},{label: 'Write candidate and receipt',- cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts',+ cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts',},{label: 'Write candidate, receipt, and review preview',- cli: 'astryx theme palette generate palette.config.json --out ocean.palette.ts --preview ocean.palette.html',+ cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts --preview themes/ocean/tokens/ocean.palette.html',},],exitCodes: [diff --git a/packages/cli/clients/cli/commands/upgrade.doc.mjs b/packages/cli/clients/cli/commands/upgrade.doc.mjsindex df19e3c141..0bc1643772 100644--- a/packages/cli/clients/cli/commands/upgrade.doc.mjs+++ b/packages/cli/clients/cli/commands/upgrade.doc.mjs@@ -53,10 +53,10 @@ export const doc = {'Exclude named codemods (repeatable). Re-run past a failed codemod by skipping it.',},{- flag: '--integration <package-or-file>',+ flag: '--integration <package>',param: 'options.integration',description:- 'Explicit integration package name or integration file path (repeatable)',+ 'Explicit integration specifier (repeatable). Resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.',default: [],},{diff --git a/packages/cli/test/cli-integrations-doc-drift.test.mjs b/packages/cli/test/cli-integrations-doc-drift.test.mjsnew file mode 100644index 0000000000..243152cbe4--- /dev/null+++ b/packages/cli/test/cli-integrations-doc-drift.test.mjs@@ -0,0 +1,455 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Documentation drift tests for the cli-integrations guide and related+ * CommandDocs/FunctionDocs. Tests verify against executable sources of truth+ * (parseDoc dispatch, resolvePackageDir, theme-discovery validators, schema+ * shapes) rather than only prose-to-prose assertions, so a behavioral change+ * that invalidates a documented claim is caught at CI time.+ */++import {afterEach, beforeEach, describe, it, expect} from 'vitest';+import {docs as integrationGuide} from '../assets/docs/cli-integrations.doc.mjs';+import {doc as upgradeCommandDoc} from '../clients/cli/commands/upgrade.doc.mjs';+import {doc as upgradeFnDoc} from '../api/upgrade/upgrade.doc.mjs';+import {doc as paletteGenerateDoc} from '../clients/cli/commands/theme-palette-generate.doc.mjs';+import {doc as integrationAddDoc} from '../clients/cli/commands/integration-add.doc.mjs';+import {parseDoc} from '../authoring/doctypes/parse.mjs';+import {parseCodemod} from '../authoring/codemod/parse.mjs';+import {resolvePackageDir} from '../foundation/integrations/integrations.mjs';+import {discoverThemeCatalog} from '../foundation/discovery/theme-discovery.mjs';+import {integrationAddTheme} from '../api/integration/add-theme.mjs';+import {themePaletteGenerate} from '../api/theme/palette/generate/generate.mjs';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';++/** Flatten all text content from a ReferenceDoc's sections into one string. */+function guideText(doc) {+ const parts = [];+ for (const section of doc.sections ?? []) {+ for (const block of section.content ?? []) {+ if (block.type === 'prose') parts.push(block.text);+ if (block.type === 'code') parts.push(block.code);+ if (block.type === 'list') parts.push((block.items ?? []).join('\n'));+ }+ }+ return parts.join('\n');+}++// ── Executable source-of-truth tests ────────────────────────────────────++describe('parseDoc dispatches on documented type stamps', () => {+ it('routes type: component to the component parser', () => {+ const doc = parseDoc({+ type: 'component',+ name: 'Test',+ description: 'x',+ props: [],+ });+ expect(doc.type).toBe('component');+ });++ it('routes type: generic to the reference parser', () => {+ const doc = parseDoc({type: 'generic', name: 'test', description: 'x'});+ expect(doc.type).toBe('generic');+ });++ it('routes type: page to the template parser', () => {+ const doc = parseDoc({+ type: 'page',+ name: 'TestPage',+ description: 'x',+ });+ expect(doc.type).toBe('page');+ });++ it('routes type: block to the template parser', () => {+ const doc = parseDoc({+ type: 'block',+ name: 'TestBlock',+ description: 'x',+ });+ expect(doc.type).toBe('block');+ });++ it('a wrong stamp misroutes: generic on a component-shaped doc drops props', () => {+ // Demonstrates the guide's claim that a wrong stamp parses under the wrong schema+ const doc = parseDoc({+ type: 'generic',+ name: 'Mislabeled',+ description: 'x',+ props: [{name: 'a', type: 'string', description: 'x'}],+ });+ // generic schema uses passthrough so props survive, but the type is generic not component+ expect(doc.type).toBe('generic');+ });+});++describe('resolvePackageDir keeps integration specs beneath node_modules', () => {+ it('rejects absolute paths', () => {+ expect(() => resolvePackageDir('/etc/passwd')).toThrow(+ /invalid integration package name/i,+ );+ });++ it('rejects relative segments', () => {+ expect(() => resolvePackageDir('../escape')).toThrow(+ /invalid integration package name/i,+ );+ });++ it('rejects dot segments', () => {+ expect(() => resolvePackageDir('./local')).toThrow(+ /invalid integration package name/i,+ );+ });++ it('accepts scoped and nested slash-separated values', () => {+ expect(() => resolvePackageDir('@acme/widgets')).not.toThrow();+ expect(() => resolvePackageDir('foo/bar')).not.toThrow();+ });+});++describe('discoverThemeCatalog validates all documented required fields', () => {+ let tmpDir;++ function writeCatalog(themes) {+ const root = path.join(tmpDir, 'themes');+ fs.mkdirSync(root, {recursive: true});+ fs.writeFileSync(+ path.join(root, 'manifest.json'),+ JSON.stringify({version: 1, themes}),+ );+ return root;+ }++ function writeThemeFiles(slug, entry, exportName) {+ const dir = path.join(tmpDir, 'themes', slug);+ fs.mkdirSync(dir, {recursive: true});+ fs.writeFileSync(+ path.join(dir, entry),+ `export const ${exportName} = {};\n`,+ );+ }++ beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'doc-drift-'));+ });+ afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+ });++ it('accepts a valid entry with all required fields', () => {+ const root = writeCatalog([+ {+ slug: 'ocean',+ displayName: 'Ocean',+ description: 'Ocean theme.',+ maintained: true,+ entry: 'oceanTheme.ts',+ exportName: 'oceanTheme',+ files: ['oceanTheme.ts'],+ },+ ]);+ writeThemeFiles('ocean', 'oceanTheme.ts', 'oceanTheme');+ expect(() => discoverThemeCatalog(root, '@test/pkg')).not.toThrow();+ });++ it('rejects missing slug', () => {+ const root = writeCatalog([+ {+ displayName: 'Ocean',+ description: 'x',+ maintained: true,+ entry: 'a.ts',+ exportName: 'a',+ files: ['a.ts'],+ },+ ]);+ expect(() => discoverThemeCatalog(root, '@test/pkg')).toThrow();+ });++ it('rejects missing displayName', () => {+ const root = writeCatalog([+ {+ slug: 'ocean',+ description: 'x',+ maintained: true,+ entry: 'a.ts',+ exportName: 'a',+ files: ['a.ts'],+ },+ ]);+ expect(() => discoverThemeCatalog(root, '@test/pkg')).toThrow();+ });++ it('rejects missing exportName', () => {+ const root = writeCatalog([+ {+ slug: 'ocean',+ displayName: 'Ocean',+ description: 'x',+ maintained: true,+ entry: 'a.ts',+ files: ['a.ts'],+ },+ ]);+ expect(() => discoverThemeCatalog(root, '@test/pkg')).toThrow();+ });++ it('rejects empty files array', () => {+ const root = writeCatalog([+ {+ slug: 'ocean',+ displayName: 'Ocean',+ description: 'x',+ maintained: true,+ entry: 'a.ts',+ exportName: 'a',+ files: [],+ },+ ]);+ expect(() => discoverThemeCatalog(root, '@test/pkg')).toThrow();+ });++ it('rejects missing maintained boolean', () => {+ const root = writeCatalog([+ {+ slug: 'ocean',+ displayName: 'Ocean',+ description: 'x',+ entry: 'a.ts',+ exportName: 'a',+ files: ['a.ts'],+ },+ ]);+ expect(() => discoverThemeCatalog(root, '@test/pkg')).toThrow();+ });++ it('requires version: 1 in the catalog root', () => {+ const root = path.join(tmpDir, 'themes');+ fs.mkdirSync(root, {recursive: true});+ fs.writeFileSync(+ path.join(root, 'manifest.json'),+ JSON.stringify({version: 2, themes: []}),+ );+ expect(() => discoverThemeCatalog(root, '@test/pkg')).toThrow(/version 1/);+ });+});++describe('documented theme palette workflow', () => {+ let tmpDir;++ beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'documented-theme-flow-'));+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: '@acme/brand-integration', version: '1.0.0'}),+ );+ });++ afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+ });++ it('generates and discovers the exact slug-relative catalog inventory', async () => {+ await integrationAddTheme('ocean', {cwd: tmpDir});+ const themeDir = path.join(tmpDir, 'themes', 'ocean');+ fs.mkdirSync(path.join(themeDir, 'tokens'), {recursive: true});+ fs.writeFileSync(+ path.join(themeDir, 'palette.config.json'),+ JSON.stringify({+ modeStrategy: 'light-only',+ stops: [20, 50, 80],+ families: [{id: 'blue', seed: '#0074e2'}],+ }),+ );++ const result = themePaletteGenerate(+ 'themes/ocean/palette.config.json',+ {out: 'themes/ocean/tokens/ocean.palette.ts'},+ {cwd: tmpDir},+ );+ expect(result.data).toMatchObject({+ output: 'themes/ocean/tokens/ocean.palette.ts',+ receipt: 'themes/ocean/tokens/ocean.palette.receipt.json',+ written: true,+ });++ fs.writeFileSync(+ path.join(themeDir, 'oceanTheme.ts'),+ "import {palette} from './tokens/ocean.palette';\nexport const oceanTheme = {palette};\n",+ );+ const catalogPath = path.join(tmpDir, 'themes', 'manifest.json');+ const catalog = JSON.parse(fs.readFileSync(catalogPath, 'utf-8'));+ catalog.themes[0].files = [+ 'oceanTheme.ts',+ 'palette.config.json',+ 'tokens/ocean.palette.ts',+ 'tokens/ocean.palette.receipt.json',+ ];+ fs.writeFileSync(catalogPath, `${JSON.stringify(catalog, null, 2)}\n`);++ expect(+ discoverThemeCatalog(+ path.join(tmpDir, 'themes'),+ '@acme/brand-integration',+ ),+ ).toEqual([expect.objectContaining({slug: 'ocean'})]);++ const text = guideText(integrationGuide);+ for (const documentedPath of catalog.themes[0].files) {+ expect(text).toContain(documentedPath);+ }+ expect(+ paletteGenerateDoc.examples.some(+ example =>+ example.cli ===+ 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts',+ ),+ ).toBe(true);+ });+});++// ── Guide prose content tests (verified against the executable tests above) ──++describe('cli-integrations guide required content', () => {+ const text = guideText(integrationGuide);++ it('documents all four type stamps used by parseDoc', () => {+ for (const stamp of ["'component'", "'generic'", "'page'", "'block'"]) {+ expect(text).toContain(stamp);+ }+ });++ it('documents both type stamps accepted by parseCodemod', () => {+ for (const type of ['code', 'config']) {+ expect(+ parseCodemod({type, title: `${type} migration`, transform() {}}).type,+ ).toBe(type);+ expect(text).toContain(`'${type}'`);+ }+ });++ it('contrasts component, doc, and template metadata suffixes', () => {+ expect(text).toContain('.doc.{ts,mjs,js}');+ expect(text).toContain('.template.{ts,mjs,js}');+ });++ it('documents the codemod version-directory layout', () => {+ expect(text).toMatch(/version-folder/i);+ expect(text).toMatch(/no `v` prefix/i);+ expect(text).toContain('0.2.0/');+ });++ it('documents that upgrade is dry-run by default with no --dry-run flag', () => {+ expect(text).toMatch(/dry-run by default/i);+ expect(text).toContain('--apply');+ expect(text).toMatch(/no `--dry-run` flag/i);+ });++ it('documents all required theme catalog manifest.json fields', () => {+ for (const field of [+ '`slug`',+ '`displayName`',+ '`description`',+ '`maintained`',+ '`entry`',+ '`exportName`',+ '`files`',+ ]) {+ expect(text).toContain(field);+ }+ expect(text).toContain('"version": 1');+ });++ it('documents the generated palette inventory exactly', () => {+ expect(text).toMatch(/already importable/i);+ expect(text).toContain('tokens/ocean.palette.ts');+ expect(text).toContain('tokens/ocean.palette.receipt.json');+ expect(text).toContain('palette.config.json');+ });++ it('documents extensionless package export subpaths', () => {+ expect(text).toMatch(/extensionless/i);+ });++ it('warns against npx for integration authoring', () => {+ expect(text).toMatch(/not.*npx/i);+ });++ it('documents that --integration resolves beneath node_modules', () => {+ expect(text).toMatch(/beneath.*node_modules/i);+ });++ it('documents integration pack --check', () => {+ expect(text).toContain('integration pack --check');+ });++ it('explains type stamp as required for new docs with legacy fallback', () => {+ expect(text).toMatch(/legacy.*stamp.*load/i);+ });+});++// ── CommandDoc / FunctionDoc consistency ─────────────────────────────────++describe('upgrade CommandDoc --integration flag', () => {+ const integrationOpt = upgradeCommandDoc.options.find(o =>+ o.flag.includes('--integration'),+ );++ it('exists', () => {+ expect(integrationOpt).toBeDefined();+ });++ it('states the actual resolver boundary', () => {+ expect(integrationOpt.description).toMatch(/beneath node_modules/i);+ expect(integrationOpt.description).toMatch(/absolute paths/i);+ expect(integrationOpt.description).toMatch(/`\.` or `\.\.`/);+ });++ it('flag placeholder does not say package-or-file', () => {+ expect(integrationOpt.flag).not.toContain('package-or-file');+ });+});++describe('upgrade FunctionDoc --integration param', () => {+ const integrationParam = upgradeFnDoc.params.find(+ p => p.name === 'options.integration',+ );++ it('exists', () => {+ expect(integrationParam).toBeDefined();+ });++ it('states the actual resolver boundary', () => {+ expect(integrationParam.description).toMatch(/beneath node_modules/i);+ expect(integrationParam.description).toMatch(/absolute paths/i);+ expect(integrationParam.description).toMatch(/`\.` or `\.\.`/);+ });+});++describe('palette generate doc mentions catalog connection', () => {+ it('description references theme catalog files array', () => {+ expect(paletteGenerateDoc.description).toMatch(/catalog/i);+ expect(paletteGenerateDoc.description).toMatch(/files.*array/i);+ });+});++describe('integration add doc has all contribution kinds', () => {+ const kindsArg = integrationAddDoc.args.find(a => a.name === 'kind');++ it('lists component, doc, template, codemod, agent-doc, and theme', () => {+ for (const kind of [+ 'component',+ 'doc',+ 'template',+ 'codemod',+ 'agent-doc',+ 'theme',+ ]) {+ expect(kindsArg.description).toContain(kind);+ }+ });+});