@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/api/docs/integrationDocs.test.mjs

@@ -0,0 +1,314 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file End-to-end tests for integration-contributed doc topics: a scaffolded
+ * consumer project whose configured integration ships a `docs` root, read back
+ * through the public surfaces — `docs()`, `search()`, and the agent-docs block.
+ *
+ * The unit-level rules (what a docs root contributes, what the catalog does
+ * with `replaces`/`extends`) are covered in
+ * foundation/discovery/docs-discovery.test.mjs. What is pinned here is that a
+ * contributed topic is indistinguishable from a built-in one at the surfaces
+ * an agent actually reads.
+ *
+ * Fixtures live 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 {docs} from './docs.mjs';
+import {search} from '../search/search.mjs';
+import {loadDocsCatalog} from './_adapter.mjs';
+import {AstryxError} from '../error.mjs';
+
+const SLOW = 30_000;
+
+let tmpDir;
+
+/** A minimal, valid topic. */
+function topic(fields) {
+  return {
+    type: 'generic',
+    name: 'deploying',
+    title: 'Deploying',
+    description: 'How to ship an app built with Acme widgets.',
+    category: 'guide',
+    sections: [
+      {title: 'Overview', content: [{type: 'prose', text: 'Push the button.'}]},
+    ],
+    ...fields,
+  };
+}
+
+/**
+ * A consumer project that configures one integration, optionally with a docs
+ * root holding the given topics.
+ * @param {Record<string, object|string>} [topics] file name → doc
+ * @param {{config?: string}} [options]
+ */
+function scaffold(topics, {config} = {}) {
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    config ?? "export default {integrations: ['@acme/widgets']};\n",
+  );
+
+  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(pkgDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default ${JSON.stringify(topics ? {docs: './docs'} : {})};\n`,
+  );
+
+  if (topics) {
+    const docsDir = path.join(pkgDir, 'docs');
+    fs.mkdirSync(docsDir, {recursive: true});
+    for (const [file, doc] of Object.entries(topics)) {
+      fs.writeFileSync(
+        path.join(docsDir, file),
+        typeof doc === 'string'
+          ? doc
+          : `export const docs = ${JSON.stringify(doc, null, 2)};\n`,
+      );
+    }
+  }
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-integration-docs-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('integration-contributed topics', () => {
+  it('lists and reads like a built-in topic, naming its owner', async () => {
+    scaffold({'deploying.doc.mjs': topic()});
+
+    const listed = await docs(undefined, undefined, {cwd: tmpDir});
+    const entry = listed.data.find(t => t.topic === 'deploying');
+    expect(entry).toMatchObject({
+      topic: 'deploying',
+      description: 'How to ship an app built with Acme widgets.',
+      package: '@acme/widgets',
+    });
+    // The built-in topics keep their own owner.
+    expect(listed.data.find(t => t.topic === 'tokens').package).toBe('@astryxdesign/cli');
+
+    const detail = await docs('deploying', undefined, {cwd: tmpDir, full: true});
+    expect(detail.type).toBe('docs.detail');
+    expect(detail.data.sections[0].content[0].text).toBe('Push the button.');
+
+    const section = await docs('deploying', 'overview', {cwd: tmpDir});
+    expect(section.data.title).toBe('Overview');
+  }, SLOW);
+
+  it('is invisible to a project that does not configure the integration', async () => {
+    scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {};\n'});
+    const listed = await docs(undefined, undefined, {cwd: tmpDir});
+    expect(listed.data.some(t => t.topic === 'deploying')).toBe(false);
+  }, SLOW);
+
+  it('serves the replacement of a built-in topic, and says what it replaced', async () => {
+    scaffold({
+      'getting-started.doc.mjs': topic({
+        name: 'getting-started',
+        replaces: 'getting-started',
+        title: 'Getting started',
+        description: 'Install Acme widgets.',
+        sections: [
+          {title: 'Install', content: [{type: 'prose', text: 'yarn add @acme/widgets'}]},
+        ],
+      }),
+    });
+
+    const detail = await docs('getting-started', undefined, {cwd: tmpDir, full: true});
+    expect(detail.data.sections.map(s => s.title)).toEqual(['Install']);
+    expect(detail.data.sections[0].content[0].text).toBe('yarn add @acme/widgets');
+
+    const listed = await docs(undefined, undefined, {cwd: tmpDir});
+    const entries = listed.data.filter(t => t.topic === 'getting-started');
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      package: '@acme/widgets',
+      replaces: 'getting-started',
+    });
+  }, SLOW);
+
+  it('keeps the replaced name resolving when the replacement renames it', async () => {
+    scaffold({
+      'setup.doc.mjs': topic({name: 'setup', replaces: 'getting-started'}),
+    });
+    const byOldName = await docs('getting-started', undefined, {cwd: tmpDir, full: true});
+    const byNewName = await docs('setup', undefined, {cwd: tmpDir, full: true});
+    expect(byOldName.data.name).toBe('setup');
+    expect(byNewName.data.name).toBe('setup');
+  }, SLOW);
+
+  it('merges an extension into the topic it extends', async () => {
+    const builtin = await docs('theme', undefined, {full: true});
+    const baseSectionTitle = builtin.data.sections[0].title;
+    scaffold({
+      'theme-internal.doc.mjs': topic({
+        name: 'theme-internal',
+        extends: 'theme',
+        sections: [
+          {title: baseSectionTitle, content: [{type: 'prose', text: 'Use the Acme theme.'}]},
+          {title: 'Acme themes', content: [{type: 'prose', text: 'Three of them.'}]},
+        ],
+      }),
+    });
+
+    const extended = await docs('theme', undefined, {cwd: tmpDir, full: true});
+    // The extension is not a topic of its own.
+    expect((await docs(undefined, undefined, {cwd: tmpDir})).data.some(
+      t => t.topic === 'theme-internal',
+    )).toBe(false);
+    expect(extended.data.sections[0].content[0].text).toBe('Use the Acme theme.');
+    expect(extended.data.sections.at(-1).title).toBe('Acme themes');
+    // Everything the extension did not name is still the base doc's.
+    expect(extended.data.sections.length).toBe(builtin.data.sections.length + 1);
+  }, SLOW);
+
+  it('migrates a real built-in section to a stable ID without duplicating it', async () => {
+    const builtin = await docs('theme', undefined, {full: true});
+    // Readers see a key on every section; the migration case is one whose
+    // source authors no id.
+    const {docs: authored} = await import('../../assets/docs/theme.doc.mjs');
+    const target = authored.sections.find(section => section.id == null);
+    expect(target).toBeDefined();
+    scaffold({
+      'theme-internal.doc.mjs': topic({
+        name: 'theme-internal',
+        extends: 'theme',
+        sections: [
+          {
+            id: 'acme-theme-setup',
+            title: target.title,
+            content: [{type: 'prose', text: 'Use the Acme theme.'}],
+          },
+        ],
+      }),
+    });
+
+    const extended = await docs('theme', undefined, {cwd: tmpDir, full: true});
+    expect(extended.data.sections).toHaveLength(builtin.data.sections.length);
+    const matches = extended.data.sections.filter(
+      section => section.title === target.title,
+    );
+    expect(matches).toEqual([
+      expect.objectContaining({
+        id: 'acme-theme-setup',
+        content: [{type: 'prose', text: 'Use the Acme theme.'}],
+      }),
+    ]);
+  }, SLOW);
+
+  it('replaces a real built-in section by the key its index shows', async () => {
+    const index = await docs('theme', undefined, {index: true});
+    const target = index.data.sections[0];
+    scaffold({
+      'theme-internal.doc.mjs': topic({
+        name: 'theme-internal',
+        extends: 'theme',
+        sections: [
+          {
+            id: target.id,
+            title: `${target.title} with Acme`,
+            content: [{type: 'prose', text: 'Acme first.'}],
+          },
+        ],
+      }),
+    });
+
+    const extended = await docs('theme', undefined, {cwd: tmpDir, full: true});
+    expect(extended.data.sections).toHaveLength(index.data.sections.length);
+    expect(extended.data.sections.filter(s => s.id === target.id)).toEqual([
+      expect.objectContaining({content: [{type: 'prose', text: 'Acme first.'}]}),
+    ]);
+    const read = await docs('theme', target.id, {cwd: tmpDir});
+    expect(read.data.title).toBe(`${target.title} with Acme`);
+  }, SLOW);
+
+  it.each(['zh', 'dense'])(
+    'replaces translated real sections by their authored titles under --%s',
+    async lang => {
+      const english = await docs('theme', undefined, {full: true});
+      const englishTitles = english.data.sections.map(section => section.title);
+      expect(englishTitles).toEqual(
+        expect.arrayContaining(['Quick Start', 'Theme Props']),
+      );
+      scaffold({
+        'theme-internal.doc.mjs': topic({
+          name: 'theme-internal',
+          extends: 'theme',
+          sections: [
+            {
+              id: 'acme-quick-start',
+              title: 'Quick Start',
+              content: [{type: 'prose', text: 'Acme quick start.'}],
+            },
+            {
+              title: 'Theme Props',
+              content: [{type: 'prose', text: 'Acme props.'}],
+            },
+          ],
+        }),
+      });
+
+      const base = await docs('theme', undefined, {lang, full: true});
+      expect(base.data.sections.map(section => section.title)).not.toEqual(
+        englishTitles,
+      );
+      const extended = await docs('theme', undefined, {cwd: tmpDir, lang, full: true});
+      expect(extended.data.sections).toHaveLength(base.data.sections.length);
+      expect(
+        extended.data.sections.filter(
+          section => section.id === 'acme-quick-start',
+        ),
+      ).toHaveLength(1);
+      expect(
+        extended.data.sections.filter(
+          section => section.content[0]?.text === 'Acme props.',
+        ),
+      ).toHaveLength(1);
+    },
+    SLOW,
+  );
+
+  it('offers the contributed topics as suggestions on an unknown one', async () => {
+    scaffold({'deploying.doc.mjs': topic()});
+    await expect(docs('nope-not-a-topic', undefined, {cwd: tmpDir, full: true})).rejects.toBeInstanceOf(
+      AstryxError,
+    );
+    try {
+      await docs('nope-not-a-topic', undefined, {cwd: tmpDir, full: true});
+    } catch (err) {
+      expect(err.suggestions.map(s => s.name)).toContain('deploying');
+    }
+  }, SLOW);
+
+  it('indexes a contributed topic in search', async () => {
+    scaffold({'deploying.doc.mjs': topic()});
+    const {data} = await search('deploying', {cwd: tmpDir, type: 'doc'});
+    expect(data.results[0]).toMatchObject({
+      domain: 'doc',
+      name: 'deploying',
+      command: 'astryx docs deploying',
+    });
+  }, SLOW);
+
+  it("falls back to the CLI's own topics when the project config is unreadable", async () => {
+    scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {integrations: 42};\n'});
+    const catalog = await loadDocsCatalog(tmpDir);
+    expect(catalog.resolve('tokens')).toBeTruthy();
+    expect(catalog.resolve('deploying')).toBeUndefined();
+  }, SLOW);
+});

package/api/doctor/doctor.d.mts

@@ -257,20 +257,15 @@ export type DoctorContext = {
      * could not be built, when it could not.
      */
     docsCatalogError?: string | null | undefined;
+    /**
+     * Combined project-level integration issues, including cross-package template replacement warnings.
+     */
     integrationIssues?: {
         package: string;
         code: string;
         severity: "warning" | "error";
         message: string;
     }[] | null | undefined;
-    /**
-     * installed dependencies whose integration manifest could not be loaded
-     * Combined project-level integration issues, including cross-package template replacement warnings.
-     */
-    autolinkFailures?: {
-        spec: string;
-        error: string;
-    }[] | null | undefined;
     /**
      * - Error thrown while resolving the config
      * path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.

package/api/doctor/doctor.doc.mjs

@@ -13,18 +13,14 @@ export const doc = {
   name: 'doctor',
   namespace: 'cli/api',
   displayName: 'doctor()',
-  summary:
-    "Check a project's Astryx setup and get a pass/warn/fail report per check. Use it as a CI gate or before debugging a broken install.",
+  summary: 'Read-only project + environment health check.',
   description:
-    'Runs a series of diagnostics: Node version, ' +
+    'Runs a series of side-effect-free diagnostics: Node version, ' +
     '@astryxdesign/core install and version alignment with the CLI, installed ' +
     'themes and wiring, astryx.config validity, integrations linked from ' +
-    'package.json without a config entry, core peer dependencies, ' +
-    'integration provider identity and contribution issues, agent docs, the ' +
-    'detected package manager, and the health of the docs the CLI reads (authoring ' +
-    'and CLI docs, the docs tree, doc size), and returns a structured ' +
-    'report. It only reads (never installs, writes, or mutates), apart from ' +
-    "importing astryx.config, which runs that file's top-level code, so it is safe " +
+    'package.json without a config entry, agent docs, core peer ' +
+    'dependencies, and the detected package manager, and returns a structured ' +
+    'report. It only reads (never installs, writes, or mutates), so it is safe ' +
     'as a CI gate and for agents to invoke.',
   importPath: '@astryxdesign/cli/api',
   signature: 'doctor(options?: DoctorOptions): Promise<DoctorResponse>',
@@ -33,23 +29,18 @@ export const doc = {
     {
       name: 'options.cwd',
       type: 'string',
-      description:
-        'Directory to diagnose. A missing directory is not an error; it shows up in the checks (e.g. core-installed: fail).',
-      default: 'process.cwd()',
+      description: 'Directory to diagnose.',
     },
   ],
   returns: [
     {
       type: 'doctor',
       description:
-        'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and an optional `fix` (always present on `warn` and `fail`; some `info` checks carry one too); plus `data.summary` with counts per status.',
+        'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass`; plus `data.summary` with counts per status.',
     },
   ],
   examples: [
-    {
-      label: 'Fail a CI step on any failed check',
-      code: 'const r = await doctor();\nif (r.data.summary.fail > 0) process.exitCode = 1;',
-    },
+    {label: 'Run diagnostics', code: 'const r = await doctor();'},
     {
       label: 'Diagnose a directory',
       code: "await doctor({cwd: '/path/to/app'});",

package/api/doctor/doctor.mjs

@@ -26,11 +26,7 @@ import * as path from 'node:path';
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/node-version.mjs';
 import {CLI_ROOT, findCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
 import {explainPackageManager, getCliInvocation} from '../../foundation/env/package-manager.mjs';
-import {
-  findConfigPath,
-  Project,
-  providerLedgerOf,
-} from '../../foundation/config/project.mjs';
+import {findConfigPath, Project} from '../../foundation/config/project.mjs';
 import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
 import {buildDocsIndexData} from '../../foundation/discovery/docs-section-key.mjs';
 import {
@@ -80,8 +76,6 @@ import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env
  * @property {string|null} [docsCatalogError] - Why the project's docs catalog
  *   could not be built, when it could not.
  * @property {Array<{package: string, code: string, severity: 'warning'|'error', message: string}>|null} [integrationIssues]
- * @property {Array<{spec: string, error: string}>|null} [autolinkFailures]
- *   installed dependencies whose integration manifest could not be loaded
  *   Combined project-level integration issues, including cross-package template replacement warnings.
  * @property {Error|null} [configError] - Error thrown while resolving the config
  *   path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
@@ -423,9 +417,6 @@ export function checkImplicitIntegrations(ctx) {
   const implicit = ctx.integrations.filter(
     integration => integration.__autolinked,
   );
-  // A dependency whose manifest cannot be loaded leaves no loaded record, so
-  // without this line doctor would say no dependency ships a manifest at all.
-  const unreadable = describeUnreadableManifests(ctx.autolinkFailures ?? []);
 
   if (implicit.length === 0) {
     return {
@@ -433,12 +424,9 @@ export function checkImplicitIntegrations(ctx) {
       label,
       status: 'info',
       message:
-        (ctx.integrations.length > 0
+        ctx.integrations.length > 0
           ? 'None — every loaded integration is named in astryx.config.'
-          : unreadable
-            ? 'None loaded.'
-            : 'None — no installed dependency ships an astryx.integration.* manifest.') +
-        unreadable,
+          : 'None — no installed dependency ships an astryx.integration.* manifest.',
     };
   }
 
@@ -451,25 +439,11 @@ export function checkImplicitIntegrations(ctx) {
       integration.__spec && integration.__spec !== integration.name
         ? ` (declared as "${integration.__spec}")`
         : '';
-    // A declared root counts only when it exists: the manifest's keys are a
-    // claim, and `integration-issues` reports the ones that are not true.
-    const declared = ['components', 'templates', 'themes', 'docs', 'codemods'].filter(
+    const roots = ['components', 'templates', 'themes', 'docs', 'codemods'].filter(
       root => integration[/** @type {'components'} */ (root)],
     );
-    const missing = declared.filter(root => {
-      const dir = integration[/** @type {'components'} */ (root)];
-      if (typeof dir !== 'string') return false;
-      const base =
-        typeof integration.__packageDir === 'string'
-          ? integration.__packageDir
-          : (ctx.cwd ?? process.cwd());
-      return !fs.existsSync(path.isAbsolute(dir) ? dir : path.resolve(base, dir));
-    });
-    const roots = declared.filter(root => !missing.includes(root));
     const contributes = roots.length > 0 ? roots.join(', ') : 'nothing';
-    const absent =
-      missing.length > 0 ? ` (declared ${missing.join(', ')} missing on disk)` : '';
-    return `${integration.name}${version}${alias} from ${integration.__dependencyField}, contributing ${contributes}${absent}`;
+    return `${integration.name}${version}${alias} from ${integration.__dependencyField}, contributing ${contributes}`;
   });
 
   const plural = implicit.length === 1 ? '' : 's';
@@ -479,8 +453,7 @@ export function checkImplicitIntegrations(ctx) {
     status: 'info',
     message:
       `${implicit.length} integration${plural} loaded from installed ` +
-      `dependencies with no astryx.config entry: ${described.join('; ')}.` +
-      unreadable,
+      `dependencies with no astryx.config entry: ${described.join('; ')}.`,
     fix:
       'Nothing to fix. Keep these dependencies installed. The CLI links them ' +
       'from package.json, so an unused-dependency check that looks only for ' +
@@ -489,30 +462,6 @@ export function checkImplicitIntegrations(ctx) {
   };
 }
 
-/**
- * The sentence `implicit-integrations` adds for dependencies whose manifest
- * could not be loaded, or '' when there are none. Still informational: the
- * package is a dependency's own bug, which `doctor integration validate`
- * diagnoses, but doctor must not report it as absent.
- * @param {Array<{spec: string, error: string}>} failures
- * @returns {string}
- */
-function describeUnreadableManifests(failures) {
-  if (failures.length === 0) return '';
-  const one = failures.length === 1;
-  const listed = failures
-    .map(({spec, error}) => {
-      const reason = String(error).split('\n')[0].slice(0, 160);
-      return `${spec} (${reason})`;
-    })
-    .join('; ');
-  return (
-    ` ${failures.length} installed ${one ? 'dependency ships' : 'dependencies ship'} ` +
-    `an astryx.integration.* manifest that could not be loaded, so ${one ? 'it contributes' : 'they contribute'} ` +
-    `nothing: ${listed}. Run \`astryx doctor integration validate <package>\` for details.`
-  );
-}
-
 /**
  * Check 7 — agent docs exist and contain the Astryx section markers.
  * @param {DoctorContext} ctx
@@ -789,26 +738,12 @@ export function checkProviderIdentity(ctx) {
     integration =>
       integration.providerId != null && integration.__loadError == null,
   ).length;
-  // An integration that could not be read has no provider ID to check, so the
-  // count above is not a complete survey. Say so instead of counting silently.
-  const unread = ctx.integrations.filter(
-    integration => integration.__loadError != null,
-  ).length;
-  const unreadNote =
-    unread === 0
-      ? ''
-      : unread === 1
-        ? ' 1 loaded integration could not be read, so its provider ID is unknown.'
-        : ` ${unread} loaded integrations could not be read, so their provider IDs are unknown.`;
   if (count === 0) {
     return {
       id,
       label,
       status: 'info',
-      message:
-        (unread === 0
-          ? 'None — no loaded integration has a provider identity.'
-          : 'No readable integration has a provider identity.') + unreadNote,
+      message: 'None — no loaded integration has a provider identity.',
     };
   }
   return {
@@ -816,10 +751,9 @@ export function checkProviderIdentity(ctx) {
     label,
     status: 'pass',
     message:
-      (count === 1
+      count === 1
         ? '1 loaded integration has its own provider ID.'
-        : `${count} loaded integrations each have their own provider ID.`) +
-      unreadNote,
+        : `${count} loaded integrations each have their own provider ID.`,
   };
 }
 
@@ -1264,25 +1198,11 @@ export async function runChecks(options = {}) {
   let docsCatalogError = null;
   /** @type {Array<{package: string, code: string, severity: 'warning'|'error', message: string}>|null} */
   let integrationIssues = null;
-  /** @type {Array<{spec: string, error: string}>|null} */
-  let autolinkFailures = null;
   try {
     const project = await Project.load(cwd);
     configTheme =
       /** @type {{theme?: string}} */ (project.config ?? {}).theme ?? null;
     integrations = project.loadedIntegrations;
-    // An installed dependency whose manifest cannot be loaded is kept out of
-    // loadedIntegrations on purpose. The provider ledger still records it.
-    autolinkFailures = [...providerLedgerOf(project).values()]
-      .filter(
-        entry =>
-          entry.outcome === 'load-failed' &&
-          entry.candidate.source === 'autolinked',
-      )
-      .map(entry => ({
-        spec: entry.candidate.spec ?? entry.label,
-        error: entry.error ?? 'its manifest could not be loaded',
-      }));
     try {
       docsCatalog = await project.docs();
       docsCatalogIssues = (await project.issues()).filter(
@@ -1309,7 +1229,6 @@ export async function runChecks(options = {}) {
     docsCatalogIssues,
     docsCatalogError,
     integrationIssues,
-    autolinkFailures,
     configError,
   };