@astryxdesign/cli 0.4.5 → 0.4.6-canary.cea9ecd

package/foundation/discovery/docs-discovery.test.mjs

@@ -0,0 +1,341 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for reference-doc discovery: what an integration's
+ * docs root contributes, what the catalog does with `replaces` / `extends`,
+ * and which authored mistakes are caught at the load boundary rather than
+ * reaching a reader as a blank section.
+ *
+ * Fixtures are scaffolded under a repo-local temp dir, not /tmp, because Vite
+ * refuses to dynamically import a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  BUILTIN_DOCS_PACKAGE,
+  DocsCatalog,
+  discoverBuiltinTopics,
+  discoverIntegrationDocs,
+  mergeTopic,
+  problemsInTopic,
+} from './docs-discovery.mjs';
+
+let tmpDir;
+
+/** A minimal, valid topic. */
+function topic(fields) {
+  return {
+    type: 'generic',
+    name: 'deploying',
+    title: 'Deploying',
+    description: 'How to ship it.',
+    sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}],
+    ...fields,
+  };
+}
+
+/** Write a docs root holding one file per topic; returns the integration. */
+function integration(name, topics, {docsDir = 'docs'} = {}) {
+  const root = path.join(tmpDir, name.replace(/[^\w]/g, '_'), docsDir);
+  fs.mkdirSync(root, {recursive: true});
+  for (const [file, value] of Object.entries(topics)) {
+    fs.writeFileSync(
+      path.join(root, file),
+      typeof value === 'string'
+        ? value
+        : `export const docs = ${JSON.stringify(value, null, 2)};\n`,
+    );
+  }
+  return {name, docs: root};
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-docs-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('discoverBuiltinTopics', () => {
+  it("finds the CLI's own topics and not their localization overlays", () => {
+    const topics = discoverBuiltinTopics();
+    expect(Object.keys(topics).length).toBeGreaterThan(0);
+    expect(topics.tokens).toMatch(/assets[/\\]docs[/\\]tokens\.doc\.mjs$/);
+    for (const name of Object.keys(topics)) {
+      expect(name).not.toMatch(/\.(zh|dense)$/);
+    }
+  });
+});
+
+describe('discoverIntegrationDocs', () => {
+  it('contributes nothing when no docs root is declared or the root is gone', async () => {
+    expect(await discoverIntegrationDocs({name: '@acme/widgets'})).toEqual({
+      records: [],
+      errors: [],
+    });
+    expect(
+      await discoverIntegrationDocs({
+        name: '@acme/widgets',
+        docs: path.join(tmpDir, 'nope'),
+      }),
+    ).toEqual({records: [], errors: []});
+  });
+
+  it('reads every topic under the root, with what it declares', async () => {
+    const {records, errors} = await discoverIntegrationDocs(
+      integration('@acme/widgets', {
+        'deploying.doc.mjs': topic(),
+        'getting-started.doc.mjs': topic({
+          name: 'getting-started',
+          title: 'Getting started',
+          replaces: 'getting-started',
+        }),
+        'theme-extra.doc.mjs': topic({name: 'theme-extra', extends: 'theme'}),
+      }),
+    );
+    expect(errors).toEqual([]);
+    expect(records.map(r => [r.name, r.package, r.replaces, r.extendsTopic])).toEqual([
+      ['deploying', '@acme/widgets', undefined, undefined],
+      ['getting-started', '@acme/widgets', 'getting-started', undefined],
+      ['theme-extra', '@acme/widgets', undefined, 'theme'],
+    ]);
+  });
+
+  it('accepts a stamped default export as well as `export const docs`', async () => {
+    const {records, errors} = await discoverIntegrationDocs(
+      integration('@acme/default-export', {
+        'deploying.doc.mjs': `export default ${JSON.stringify(topic())};\n`,
+      }),
+    );
+    expect(errors).toEqual([]);
+    expect(records.map(r => r.name)).toEqual(['deploying']);
+  });
+
+  it('ignores a localization overlay beside a topic', async () => {
+    const {records} = await discoverIntegrationDocs(
+      integration('@acme/localized', {
+        'deploying.doc.mjs': topic(),
+        'deploying.doc.zh.mjs': `export const docsZh = {description: '部署', sections: []};\n`,
+      }),
+    );
+    expect(records.map(r => r.name)).toEqual(['deploying']);
+  });
+
+  it('reports a doc that exports nothing, rather than skipping it silently', async () => {
+    const {records, errors} = await discoverIntegrationDocs(
+      integration('@acme/empty', {'deploying.doc.mjs': 'export const nope = 1;\n'}),
+    );
+    expect(records).toEqual([]);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('exports no doc');
+  });
+
+  it('reports two files claiming one topic name', async () => {
+    const {records, errors} = await discoverIntegrationDocs(
+      integration('@acme/dupes', {
+        'a-deploying.doc.mjs': topic(),
+        'b-deploying.doc.mjs': topic({title: 'Deploying, again'}),
+      }),
+    );
+    expect(records).toHaveLength(1);
+    expect(errors[0].message).toContain('both define the topic "deploying"');
+  });
+
+  it('reports a doc that both replaces and extends', async () => {
+    const {records, errors} = await discoverIntegrationDocs(
+      integration('@acme/both', {
+        'deploying.doc.mjs': topic({replaces: 'theme', extends: 'theme'}),
+      }),
+    );
+    expect(records).toEqual([]);
+    expect(errors[0].message).toContain('declares both');
+  });
+});
+
+describe('problemsInTopic', () => {
+  it('passes a well-formed topic', () => {
+    expect(problemsInTopic(topic())).toEqual([]);
+  });
+
+  it('catches the mistakes that would render as a blank section', () => {
+    expect(problemsInTopic(topic({title: ''}))).toContain(
+      'title: expected a non-empty string',
+    );
+    expect(problemsInTopic(topic({sections: []}))).toContain(
+      'sections: expected at least one section',
+    );
+    // A misspelled required field: the block renders nothing at all.
+    expect(
+      problemsInTopic(
+        topic({sections: [{title: 'Overview', content: [{type: 'prose', txt: 'oops'}]}]}),
+      ),
+    ).toEqual([
+      'sections[0].content[0].text: required for a prose block',
+      'sections[0].content[0].txt: not a field of a prose block',
+    ]);
+    // A heading level the renderer does not index.
+    expect(
+      problemsInTopic(
+        topic({
+          sections: [{title: 'Overview', content: [{type: 'heading', level: 2, text: 'x'}]}],
+        }),
+      ),
+    ).toContain('sections[0].content[0].level: 2 is not one of 3, 4, 5, 6');
+    // A short row renders blank cells; a long one drops its tail.
+    expect(
+      problemsInTopic(
+        topic({
+          sections: [
+            {
+              title: 'Overview',
+              content: [{type: 'table', headers: ['A', 'B'], rows: [['1']]}],
+            },
+          ],
+        }),
+      ),
+    ).toContain('sections[0].content[0].rows[0]: has 1 cells but the table has 2 headers');
+  });
+
+  it('rejects a name that is not URL-safe', () => {
+    expect(problemsInTopic(topic({name: 'not a topic'})).join('\n')).toContain('URL-safe');
+  });
+});
+
+describe('DocsCatalog', () => {
+  const record = fields => ({
+    name: 'deploying',
+    package: '@acme/widgets',
+    path: '/pkg/docs/deploying.doc.mjs',
+    ...fields,
+  });
+
+  it('starts from the built-in topics, owned by the CLI', () => {
+    const catalog = DocsCatalog.fromBuiltins({tokens: '/cli/tokens.doc.mjs'});
+    expect(catalog.names()).toEqual(['tokens']);
+    expect(catalog.resolve('tokens').package).toBe(BUILTIN_DOCS_PACKAGE);
+    expect(catalog.resolve('TOKENS').name).toBe('tokens');
+    expect(catalog.resolve('nope')).toBeUndefined();
+    expect(catalog.resolve(42)).toBeUndefined();
+  });
+
+  it('adds a new topic', () => {
+    const catalog = DocsCatalog.fromBuiltins({tokens: '/cli/tokens.doc.mjs'});
+    expect(catalog.add(record())).toBeNull();
+    expect(catalog.names()).toEqual(['tokens', 'deploying']);
+    expect(catalog.resolve('deploying').package).toBe('@acme/widgets');
+  });
+
+  it('refuses to shadow an existing topic by name alone', () => {
+    const catalog = DocsCatalog.fromBuiltins({tokens: '/cli/tokens.doc.mjs'});
+    const issue = catalog.add(record({name: 'tokens'}));
+    expect(issue).toMatchObject({code: 'invalid_doc', severity: 'error'});
+    expect(issue.message).toContain("already provided by @astryxdesign/cli");
+    expect(issue.message).toContain("replaces: 'tokens'");
+    // The built-in topic is untouched.
+    expect(catalog.resolve('tokens').package).toBe(BUILTIN_DOCS_PACKAGE);
+  });
+
+  it('replaces a topic in place, keeping its position', () => {
+    const catalog = DocsCatalog.fromBuiltins({
+      'getting-started': '/cli/getting-started.doc.mjs',
+      tokens: '/cli/tokens.doc.mjs',
+    });
+    expect(
+      catalog.add(record({name: 'getting-started', replaces: 'getting-started'})),
+    ).toBeNull();
+    expect(catalog.names()).toEqual(['getting-started', 'tokens']);
+    const entry = catalog.resolve('getting-started');
+    expect(entry.package).toBe('@acme/widgets');
+    expect(entry.replaces).toBe('getting-started');
+  });
+
+  it('leaves the old name as an alias when the replacement renames it', () => {
+    const catalog = DocsCatalog.fromBuiltins({
+      'getting-started': '/cli/getting-started.doc.mjs',
+    });
+    catalog.add(record({name: 'setup', replaces: 'getting-started'}));
+    expect(catalog.names()).toEqual(['setup']);
+    expect(catalog.resolve('getting-started').name).toBe('setup');
+    expect(catalog.resolve('setup').name).toBe('setup');
+  });
+
+  it('keeps every name a twice-renamed topic has answered to', () => {
+    const catalog = DocsCatalog.fromBuiltins({
+      'getting-started': '/cli/getting-started.doc.mjs',
+    });
+    catalog.add(record({name: 'setup', replaces: 'getting-started'}));
+    catalog.add(
+      record({name: 'install', package: '@acme/later', replaces: 'setup'}),
+    );
+    expect(catalog.resolve('getting-started').name).toBe('install');
+    expect(catalog.resolve('setup').name).toBe('install');
+  });
+
+  it('warns, and lets the later package win, when two replace one topic', () => {
+    const catalog = DocsCatalog.fromBuiltins({tokens: '/cli/tokens.doc.mjs'});
+    expect(catalog.add(record({name: 'tokens', replaces: 'tokens'}))).toBeNull();
+    const issue = catalog.add(
+      record({name: 'tokens', package: '@acme/later', replaces: 'tokens'}),
+    );
+    expect(issue).toMatchObject({code: 'duplicate_doc', severity: 'warning'});
+    expect(issue.message).toContain('@acme/later is configured later, so it wins');
+    expect(catalog.resolve('tokens').package).toBe('@acme/later');
+  });
+
+  it('records an extension against its target rather than adding a topic', () => {
+    const catalog = DocsCatalog.fromBuiltins({theme: '/cli/theme.doc.mjs'});
+    expect(
+      catalog.add(record({name: 'theme-extra', extendsTopic: 'theme'})),
+    ).toBeNull();
+    expect(catalog.names()).toEqual(['theme']);
+    expect(catalog.resolve('theme').extensions).toEqual([
+      {package: '@acme/widgets', path: '/pkg/docs/deploying.doc.mjs'},
+    ]);
+  });
+
+  it('reports a replace/extend target that no package provides', () => {
+    const catalog = DocsCatalog.fromBuiltins({tokens: '/cli/tokens.doc.mjs'});
+    expect(catalog.add(record({replaces: 'nope'}))).toMatchObject({
+      code: 'invalid_doc',
+      severity: 'error',
+    });
+    expect(catalog.add(record({extendsTopic: 'nope'}))).toMatchObject({
+      code: 'invalid_doc',
+      severity: 'error',
+    });
+    expect(catalog.names()).toEqual(['tokens']);
+  });
+});
+
+describe('mergeTopic', () => {
+  const base = {
+    title: 'Theme',
+    description: 'Theming.',
+    sections: [
+      {title: 'Install', content: [{type: 'prose', text: 'npm i'}]},
+      {title: 'Tokens', content: [{type: 'prose', text: 'use tokens'}]},
+    ],
+  };
+
+  it('replaces a section by title, appends a new one, and leaves the rest', () => {
+    const merged = mergeTopic(base, {
+      sections: [
+        {title: 'Install', content: [{type: 'prose', text: 'yarn add'}]},
+        {title: 'Internal', content: [{type: 'prose', text: 'the meta way'}]},
+      ],
+    });
+    expect(merged.sections.map(s => s.title)).toEqual(['Install', 'Tokens', 'Internal']);
+    expect(merged.sections[0].content[0].text).toBe('yarn add');
+    expect(merged.sections[1].content[0].text).toBe('use tokens');
+    // The base is untouched.
+    expect(base.sections[0].content[0].text).toBe('npm i');
+  });
+
+  it('takes the title and description only when the overlay states them', () => {
+    expect(mergeTopic(base, {sections: []}).title).toBe('Theme');
+    expect(mergeTopic(base, {title: 'Theming', sections: []}).title).toBe('Theming');
+  });
+});

package/foundation/integrations/integrations.d.mts

@@ -38,15 +38,16 @@ export function loadIntegrations(specs?: string[], { cwd }?: {
 }): Promise<LoadedIntegration[]>;
 /**
  * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
- * the package's package.json; the `components`/`templates`/`codemods` roots are
- * absolute paths resolved from the manifest. The `__`-prefixed fields are
- * internal bookkeeping used by validate-integration and Project.
+ * the package's package.json; the `components`/`templates`/`codemods`/`docs`
+ * roots are absolute paths resolved from the manifest. The `__`-prefixed fields
+ * are internal bookkeeping used by validate-integration and Project.
  * @typedef {object} LoadedIntegration
  * @property {string} name
  * @property {string} [version]
  * @property {string} [components]
  * @property {string} [templates]
  * @property {string} [codemods]
+ * @property {string} [docs]
  * @property {string} [issuesUrl]
  * @property {string} __spec
  * @property {string} __packageDir
@@ -58,9 +59,9 @@ export function loadIntegrations(specs?: string[], { cwd }?: {
 export const MANIFEST_BASENAMES: string[];
 /**
  * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
- * the package's package.json; the `components`/`templates`/`codemods` roots are
- * absolute paths resolved from the manifest. The `__`-prefixed fields are
- * internal bookkeeping used by validate-integration and Project.
+ * the package's package.json; the `components`/`templates`/`codemods`/`docs`
+ * roots are absolute paths resolved from the manifest. The `__`-prefixed fields
+ * are internal bookkeeping used by validate-integration and Project.
  */
 export type LoadedIntegration = {
     name: string;
@@ -68,6 +69,7 @@ export type LoadedIntegration = {
     components?: string | undefined;
     templates?: string | undefined;
     codemods?: string | undefined;
+    docs?: string | undefined;
     issuesUrl?: string | undefined;
     __spec: string;
     __packageDir: string;

package/foundation/integrations/integrations.mjs

@@ -6,7 +6,7 @@
  * Integrations are PACKAGE NAMES listed in astryx.config.{ts,mjs,js}. Each
  * package declares a single conventional root manifest sibling to its
  * package.json — astryx.integration.{ts,mjs,js} — which contributes
- * components/templates/codemods roots and an optional issuesUrl. Identity
+ * components/templates/codemods/docs roots and an optional issuesUrl. Identity
  * (name, version) comes from the package's package.json, not the manifest.
  */
 
@@ -18,15 +18,16 @@ import {loadModuleWithParser, findPresentFiles} from '../fs/module-loader.mjs';
 
 /**
  * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
- * the package's package.json; the `components`/`templates`/`codemods` roots are
- * absolute paths resolved from the manifest. The `__`-prefixed fields are
- * internal bookkeeping used by validate-integration and Project.
+ * the package's package.json; the `components`/`templates`/`codemods`/`docs`
+ * roots are absolute paths resolved from the manifest. The `__`-prefixed fields
+ * are internal bookkeeping used by validate-integration and Project.
  * @typedef {object} LoadedIntegration
  * @property {string} name
  * @property {string} [version]
  * @property {string} [components]
  * @property {string} [templates]
  * @property {string} [codemods]
+ * @property {string} [docs]
  * @property {string} [issuesUrl]
  * @property {string} __spec
  * @property {string} __packageDir
@@ -187,6 +188,7 @@ export async function loadIntegrations(specs = [], {cwd = process.cwd()} = {}) {
       components: resolveRoot(manifest.components),
       templates: resolveRoot(manifest.templates),
       codemods: resolveRoot(manifest.codemods),
+      docs: resolveRoot(manifest.docs),
       issuesUrl: manifest.issuesUrl,
       __spec: spec,
       __packageDir: packageDir,

package/foundation/integrations/validate-contributions.mjs

@@ -23,6 +23,7 @@ import * as fs from 'node:fs';
 import {discoverIntegrationCodemods} from '../../assets/codemods/integration-discovery.mjs';
 import {discoverIntegrationTemplatesForOne} from '../discovery/template-adapter.mjs';
 import * as componentDiscovery from '../discovery/component-discovery.mjs';
+import {discoverIntegrationDocs} from '../discovery/docs-discovery.mjs';
 
 /**
  * @typedef {import('./issue').AstryxIntegrationIssue} Issue
@@ -37,12 +38,12 @@ export function issueError(code, message) {
 /**
  * Verify each declared contribution root exists on disk. A declared-but-missing
  * root is a `missing_root` error.
- * @param {{components?: string, templates?: string, codemods?: string}} resolved
+ * @param {{components?: string, templates?: string, codemods?: string, docs?: string}} resolved
  *   absolute resolved roots (undefined when not declared)
  * @param {Issue[]} issues
  */
 function checkRoots(resolved, issues) {
-  const kinds = /** @type {const} */ (['components', 'templates', 'codemods']);
+  const kinds = /** @type {const} */ (['components', 'templates', 'codemods', 'docs']);
   for (const kind of kinds) {
     const root = resolved[kind];
     if (root == null) continue;
@@ -124,6 +125,31 @@ async function checkComponents(integration, issues) {
   }
 }
 
+/**
+ * Validate the integration's doc topics via the landed discovery. A doc that
+ * cannot be loaded, is not a usable topic, or collides with a sibling is
+ * reported as an `invalid_doc` error.
+ *
+ * Only per-file problems are visible here: a topic that collides with another
+ * PACKAGE's, or names a `replaces`/`extends` target that does not exist, can
+ * only be judged once every integration is resolved together, so those are
+ * raised by `Project.docs()` instead.
+ *
+ * @param {LoadedIntegration} integration loaded-integration-shaped object
+ * @param {Issue[]} issues
+ */
+async function checkDocs(integration, issues) {
+  if (!integration.docs || !fs.existsSync(integration.docs)) return;
+  try {
+    const {errors} = await discoverIntegrationDocs(integration);
+    for (const e of errors) {
+      issues.push(issueError('invalid_doc', e.message));
+    }
+  } catch (err) {
+    issues.push(issueError('invalid_doc', /** @type {any} */ (err).message));
+  }
+}
+
 /**
  * Run every contribution validator against a loaded-integration-shaped object.
  * @param {LoadedIntegration} integration
@@ -133,6 +159,7 @@ async function runContributionChecks(integration, issues) {
   await checkCodemods(integration, issues);
   await checkTemplates(integration, issues);
   await checkComponents(integration, issues);
+  await checkDocs(integration, issues);
 }
 
 /**
@@ -161,6 +188,7 @@ export async function validateLoadedIntegration(loaded) {
       components: loaded.components,
       templates: loaded.templates,
       codemods: loaded.codemods,
+      docs: loaded.docs,
     },
     issues,
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.4.5",
+  "version": "0.4.6-canary.cea9ecd",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -87,10 +87,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.4.6-canary.cea9ecd",
+    "@astryxdesign/core": "0.4.6-canary.cea9ecd",
+    "@astryxdesign/lab": "0.4.6-canary.cea9ecd",
+    "@astryxdesign/theme-neutral": "0.4.6-canary.cea9ecd",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -108,10 +108,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.4.6-canary.cea9ecd",
+    "@astryxdesign/core": "0.4.6-canary.cea9ecd",
+    "@astryxdesign/lab": "0.4.6-canary.cea9ecd",
+    "@astryxdesign/theme-neutral": "0.4.6-canary.cea9ecd",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {