@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/foundation/config/project.test.mjs

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import {Project, DEFAULT_ISSUES_URL, findConfigPath} from './project.mjs';
 import {InMemoryConfigCache} from './config-cache.mjs';
 import * as componentDiscovery from '../discovery/component-discovery.mjs';
+import {discoverCoreTemplates} from '../discovery/template-adapter.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -21,6 +22,9 @@ function scaffold({
   issuesUrl,
   withComponents = true,
   withTemplates = true,
+  templateId = 'hero',
+  templateType = 'block',
+  templateReplaces = null,
   withCodemods = true,
   brokenComponent = false,
   brokenCodemod = false,
@@ -65,7 +69,7 @@ function scaffold({
     fs.mkdirSync(compDir, {recursive: true});
     fs.writeFileSync(
       path.join(compDir, 'Widget.doc.mjs'),
-      `export const docs = { name: 'Widget', usage: {description: 'A widget'} };\n`,
+      `export const docs = { name: 'Widget', usage: {description: 'A widget'}, props: [] };\n`,
     );
     if (!brokenComponent) {
       fs.writeFileSync(
@@ -80,12 +84,12 @@ function scaffold({
     const tDir = path.join(pkgDir, 'templates');
     fs.mkdirSync(tDir, {recursive: true});
     fs.writeFileSync(
-      path.join(tDir, 'hero.doc.mjs'),
-      `export default { type: 'block', name: 'Hero', description: 'A hero' };\n`,
+      path.join(tDir, `${templateId}.doc.mjs`),
+      `export default { type: '${templateType}', name: 'Fixture template', description: 'A fixture template'${templateReplaces == null ? '' : `, replaces: ${JSON.stringify(templateReplaces)}`} };\n`,
     );
     fs.writeFileSync(
-      path.join(tDir, 'hero.tsx'),
-      `export default function Hero() { return null; }\n`,
+      path.join(tDir, `${templateId}.tsx`),
+      `export default function FixtureTemplate() { return null; }\n`,
     );
   }
 
@@ -163,7 +167,7 @@ function scaffoldLocalPackage({name = '@acme/local'} = {}) {
 
   fs.mkdirSync(path.join(tmpDir, 'templates'));
   fs.writeFileSync(
-    path.join(tmpDir, 'templates', 'local-page.template.mjs'),
+    path.join(tmpDir, 'templates', 'local-page.doc.mjs'),
     `export default {type: 'page', name: 'Local page', description: 'Local page.'};\n`,
   );
   fs.writeFileSync(
@@ -181,21 +185,8 @@ function scaffoldLocalPackage({name = '@acme/local'} = {}) {
 
   fs.mkdirSync(path.join(tmpDir, 'themes', 'ocean'), {recursive: true});
   fs.writeFileSync(
-    path.join(tmpDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug: 'ocean',
-          displayName: 'Ocean',
-          description: 'Ocean theme.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.doc.mjs'),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Ocean theme.', maintained: true};\n`,
   );
   fs.writeFileSync(
     path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
@@ -337,6 +328,91 @@ describe('Project discovery', () => {
     expect(hero.type).toBe('block');
   });
 
+  it('templates() projects a valid integration replacement instead of its Core target', async () => {
+    const corePage = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(corePage).toBeDefined();
+    scaffold({
+      templateId: 'acme-app-shell',
+      templateType: 'page',
+      templateReplaces: corePage.dirName,
+    });
+    const project = await Project.load(tmpDir);
+
+    const templates = await project.templates();
+
+    expect(
+      templates.find(template => template.dirName === 'acme-app-shell'),
+    ).toMatchObject({
+      package: '@acme/widgets',
+      replaces: corePage.dirName,
+    });
+    expect(
+      templates.find(
+        template =>
+          template.dirName === corePage.dirName &&
+          template.package !== '@acme/widgets',
+      ),
+    ).toBeUndefined();
+    expect(await project.issues()).toEqual([]);
+  });
+
+  it('reports replacement issues regardless of discovery call order without hiding other contributions', async () => {
+    scaffold({
+      templateReplaces: 'missing-core-template',
+    });
+
+    const componentsFirst = await Project.load(tmpDir);
+    expect(
+      (await componentsFirst.components()).some(
+        component => component.package === '@acme/widgets',
+      ),
+    ).toBe(true);
+    expect(await componentsFirst.issues()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          package: '@acme/widgets',
+        }),
+      ]),
+    );
+
+    const issuesFirst = await Project.load(tmpDir, {fresh: true});
+    expect(await issuesFirst.issues()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          package: '@acme/widgets',
+        }),
+      ]),
+    );
+    expect(
+      (await issuesFirst.components()).some(
+        component => component.package === '@acme/widgets',
+      ),
+    ).toBe(true);
+    const ownTemplate = (await issuesFirst.templates()).find(
+      template =>
+        template.package === '@acme/widgets' && template.dirName === 'hero',
+    );
+    expect(ownTemplate).toBeDefined();
+    expect(ownTemplate).not.toHaveProperty('replaces');
+
+    const sharedCache = new InMemoryConfigCache();
+    const warm = await Project.load(tmpDir, {cache: sharedCache});
+    await warm.templates();
+    const cached = await Project.load(tmpDir, {cache: sharedCache});
+    expect(await cached.issues()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          package: '@acme/widgets',
+        }),
+      ]),
+    );
+  });
+
   it('codemods() returns core registry groups + integration groups', async () => {
     scaffold();
     const project = await Project.load(tmpDir);
@@ -481,6 +557,53 @@ describe('Project issues (skip + warn)', () => {
     expect(issues.some(i => i.package === '@acme/widgets')).toBe(true);
   });
 
+  it('keeps valid contribution kinds and siblings when others are broken', async () => {
+    const pkgDir = scaffold({brokenComponent: true});
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'broken.template.mjs'),
+      `export default {type: 'block', name: 'Broken', description: 'Missing source'};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'ValidWidget.doc.mjs'),
+      `export default {type: 'component', name: 'ValidWidget', props: []};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'ValidWidget.tsx'),
+      `export function ValidWidget() { return null; }\n`,
+    );
+    const project = await Project.load(tmpDir);
+
+    const templates = await project.templates();
+    const components = await project.components();
+    const issues = await project.issues();
+
+    expect(
+      templates.find(
+        template =>
+          template.dirName === 'hero' && template.package === '@acme/widgets',
+      ),
+    ).toBeDefined();
+    expect(
+      components.find(
+        component =>
+          component.name === 'ValidWidget' &&
+          component.package === '@acme/widgets',
+      ),
+    ).toBeDefined();
+    expect(
+      components.find(
+        component =>
+          component.name === 'Widget' && component.package === '@acme/widgets',
+      ),
+    ).toBeUndefined();
+    expect(issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({code: 'invalid_component'}),
+        expect.objectContaining({code: 'invalid_template'}),
+      ]),
+    );
+  });
+
   it('does not throw when an integration codemod is broken', async () => {
     scaffold({brokenCodemod: true});
     const project = await Project.load(tmpDir);
@@ -515,6 +638,132 @@ describe('Project issues (skip + warn)', () => {
   });
 });
 
+describe('Project loads each integration in isolation', () => {
+  /**
+   * Install a package under node_modules with the given root files.
+   * @param {string} name
+   * @param {string[]} manifests manifest basenames to write
+   */
+  function installPackage(name, manifests) {
+    const dir = path.join(tmpDir, 'node_modules', ...name.split('/'));
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({name, version: '1.0.0'}),
+    );
+    for (const file of manifests) {
+      fs.writeFileSync(path.join(dir, file), 'export default {};\n');
+    }
+  }
+
+  /** @param {string[]} integrations */
+  function writeConfig(integrations) {
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default ${JSON.stringify({integrations})};\n`,
+    );
+  }
+
+  /** @param {Project} project */
+  async function widgetComponents(project) {
+    return (await project.components())
+      .filter(component => component.package === '@acme/widgets')
+      .map(component => component.name);
+  }
+
+  it.each([
+    ['is not installed', '@acme/broken', () => {}, /Install it first/],
+    [
+      'has no root manifest',
+      '@acme/broken',
+      () => installPackage('@acme/broken', []),
+      /no conventional root manifest/,
+    ],
+    [
+      'has two root manifests',
+      '@acme/broken',
+      () =>
+        installPackage('@acme/broken', [
+          'astryx.integration.mjs',
+          'astryx.integration.js',
+        ]),
+      /multiple root manifests/,
+    ],
+    [
+      'is not a bare package name',
+      '../escape',
+      () => {},
+      /Invalid integration package name/,
+    ],
+  ])(
+    'keeps the others when a configured package %s',
+    async (_label, spec, install, message) => {
+      scaffold();
+      install();
+      writeConfig([spec, '@acme/widgets']);
+
+      const project = await Project.load(tmpDir);
+
+      expect(await widgetComponents(project)).toEqual(['Widget']);
+      expect(await project.issues()).toContainEqual(
+        expect.objectContaining({
+          package: spec,
+          code: 'integration_error',
+          message: expect.stringMatching(message),
+        }),
+      );
+    },
+  );
+
+  it('keeps configured integrations when the package being authored has two root manifests', async () => {
+    scaffold();
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/local', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.js'),
+      'export default {};\n',
+    );
+
+    const project = await Project.load(tmpDir);
+
+    expect(await widgetComponents(project)).toEqual(['Widget']);
+    expect(await project.issues()).toContainEqual(
+      expect.objectContaining({
+        package: '@acme/local',
+        code: 'integration_error',
+        message: expect.stringMatching(/multiple root manifests/),
+      }),
+    );
+  });
+
+  it('puts the package being authored at its configured position when the config names it', async () => {
+    scaffold();
+    scaffoldLocalPackage({name: '@acme/local'});
+    writeConfig(['@acme/local', '@acme/widgets']);
+
+    const project = await Project.load(tmpDir);
+
+    expect(
+      project.loadedIntegrations.map(integration => [
+        integration.name,
+        Boolean(integration.__local),
+      ]),
+    ).toEqual([
+      ['@acme/local', true],
+      ['@acme/widgets', false],
+    ]);
+    expect(await project.issues()).not.toContainEqual(
+      expect.objectContaining({package: '@acme/local', code: 'integration_error'}),
+    );
+  });
+});
+
 describe('Project.issuesUrl routing', () => {
   it('routes core to config.issuesUrl, falling back to the default', async () => {
     scaffold({issuesUrl: 'https://example.com/core'});

package/foundation/discovery/authoring-self-docs.d.mts

@@ -0,0 +1,87 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Every `*.doc.mjs` under `root`, relative and sorted.
+ * @param {string} [root]
+ * @returns {string[]}
+ */
+export function discoverAuthoringSelfDocSources(root?: string): string[];
+/**
+ * Import each self-doc. One that fails is reported, never thrown, so one bad
+ * file cannot take the rest of the topic down with it.
+ * @param {string[]} [sources]
+ * @param {string} [root]
+ * @returns {Promise<{loaded: {source: string, doc: any}[], failed: {source: string, error: string}[]}>}
+ */
+export function loadAuthoringSelfDocs(sources?: string[], root?: string): Promise<{
+    loaded: {
+        source: string;
+        doc: any;
+    }[];
+    failed: {
+        source: string;
+        error: string;
+    }[];
+}>;
+/**
+ * A schema's fields as the table its section prints, each nested field on the
+ * row after its parent; null when there are none. A reference block that
+ * names some of a schema's fields includes this table of just those.
+ * @param {any[]} fields
+ * @returns {{type: 'table', headers: string[], rows: string[][]} | null}
+ */
+export function schemaFieldTable(fields: any[]): {
+    type: "table";
+    headers: string[];
+    rows: string[][];
+} | null;
+/**
+ * One self-doc as a topic section, keyed by the doc's own name.
+ * @param {any} doc
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
+ */
+export function selfDocSection(doc: any): import("../../authoring/doctypes/reference/type").ReferenceSection;
+/**
+ * The `authoring` topic: one section per self-doc, in the order given.
+ * @param {any[]} docs
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceDoc}
+ */
+export function buildAuthoringReferenceDoc(docs: any[]): import("../../authoring/doctypes/reference/type").ReferenceDoc;
+/**
+ * The `authoring` topic from every self-doc that loads. One that fails is left
+ * out here and reported by {@link auditAuthoringSelfDocs}.
+ * @returns {Promise<import('../../authoring/doctypes/reference/type').ReferenceDoc>}
+ */
+export function buildAuthoringTopic(): Promise<import("../../authoring/doctypes/reference/type").ReferenceDoc>;
+/**
+ * What stands between a self-doc and a reader of `astryx docs authoring`.
+ * @param {{root?: string, sources?: string[], budget?: number}} [options]
+ * @returns {Promise<{
+ *   sections: number,
+ *   unreachable: string[],
+ *   failed: {source: string, error: string}[],
+ *   oversized: {key: string, title: string, bytes: number}[],
+ * }>}
+ */
+export function auditAuthoringSelfDocs({ root, sources, budget, }?: {
+    root?: string;
+    sources?: string[];
+    budget?: number;
+}): Promise<{
+    sections: number;
+    unreachable: string[];
+    failed: {
+        source: string;
+        error: string;
+    }[];
+    oversized: {
+        key: string;
+        title: string;
+        bytes: number;
+    }[];
+}>;
+/** The directory the self-docs live under. */
+export const AUTHORING_ROOT: string;
+/** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
+export const AUTHORING_SELF_DOCS: string[];

package/foundation/discovery/authoring-self-docs.mjs

@@ -0,0 +1,237 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The authoring self-docs, and the `authoring` topic built from them.
+ *
+ * @input The SchemaDoc each authoring module colocates as `*.doc.mjs` under
+ *   packages/cli/authoring.
+ * @output {@link AUTHORING_SELF_DOCS} (every self-doc, in reading order), the
+ *   `authoring` reference topic with one section per self-doc, and an audit
+ *   naming any self-doc the topic cannot reach, any that fails to load, and any
+ *   section over the docs output budget.
+ * @position Read by assets/docs/authoring.doc.mjs (the topic) and by Doctor
+ *   (the audit). Lives in foundation because authoring/ holds only contracts.
+ *   A new `*.doc.mjs` under authoring/ must be added to the list, or Doctor and
+ *   the self-doc tests fail.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {CLI_ROOT} from '../fs/paths.mjs';
+import {readDocView} from '../doc-compiler/read.mjs';
+import {
+  DOC_OUTPUT_BUDGET_BYTES,
+  oversizedDocSections,
+} from './docs-output-budget.mjs';
+
+/** The directory the self-docs live under. */
+export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
+
+/** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
+export const AUTHORING_SELF_DOCS = [
+  'integration/integration.doc.mjs',
+  'config/config.doc.mjs',
+  'debug/debug.doc.mjs',
+  'gap-report/gap-report.doc.mjs',
+  'discover/discover.doc.mjs',
+  'codemod/codemod.doc.mjs',
+  'identity/identity.doc.mjs',
+  'doctypes/base/graph-fields.doc.mjs',
+  'doctypes/component/component.doc.mjs',
+  'doctypes/hook/hook.doc.mjs',
+  'doctypes/function/function.doc.mjs',
+  'doctypes/command/command.doc.mjs',
+  'doctypes/enum/enum.doc.mjs',
+  'doctypes/namespace/namespace.doc.mjs',
+  'doctypes/reference/reference.doc.mjs',
+  'doctypes/schema/schema.doc.mjs',
+  'doctypes/template/template.doc.mjs',
+  'doctypes/theme/theme.doc.mjs',
+];
+
+/** Blocks a self-doc note may carry that a topic section can render. */
+const TOPIC_BLOCKS = new Set(['prose', 'list', 'code', 'heading', 'table']);
+
+/**
+ * Every `*.doc.mjs` under `root`, relative and sorted.
+ * @param {string} [root]
+ * @returns {string[]}
+ */
+export function discoverAuthoringSelfDocSources(root = AUTHORING_ROOT) {
+  /** @type {string[]} */
+  const found = [];
+  /** @param {string} dir */
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('__'))
+        continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.doc.mjs')) {
+        found.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  walk(root);
+  return found.sort();
+}
+
+/**
+ * Import each self-doc. One that fails is reported, never thrown, so one bad
+ * file cannot take the rest of the topic down with it.
+ * @param {string[]} [sources]
+ * @param {string} [root]
+ * @returns {Promise<{loaded: {source: string, doc: any}[], failed: {source: string, error: string}[]}>}
+ */
+export async function loadAuthoringSelfDocs(
+  sources = AUTHORING_SELF_DOCS,
+  root = AUTHORING_ROOT,
+) {
+  const loaded = [];
+  const failed = [];
+  for (const source of sources) {
+    try {
+      const doc = await readDocView(path.join(root, source), {
+        root: 'self-docs',
+        loader: 'native',
+      });
+      if (
+        typeof doc?.name !== 'string' ||
+        typeof doc?.description !== 'string'
+      ) {
+        throw new Error('exports no doc with a name and a description');
+      }
+      loaded.push({source, doc});
+    } catch (error) {
+      failed.push({
+        source,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return {loaded, failed};
+}
+
+/**
+ * @param {any[]} fields
+ * @returns {string[][]}
+ */
+function fieldRows(fields) {
+  return fields.flatMap(field => [
+    [
+      String(field.name),
+      String(field.type ?? ''),
+      field.required ? 'yes' : 'no',
+      [
+        field.description,
+        field.default != null ? `Default: ${field.default}.` : null,
+        field.example != null ? `Example: ${field.example}.` : null,
+      ]
+        .filter(Boolean)
+        .join(' '),
+    ],
+    ...fieldRows(field.fields ?? []),
+  ]);
+}
+
+/**
+ * A schema's fields as the table its section prints, each nested field on the
+ * row after its parent; null when there are none. A reference block that
+ * names some of a schema's fields includes this table of just those.
+ * @param {any[]} fields
+ * @returns {{type: 'table', headers: string[], rows: string[][]} | null}
+ */
+export function schemaFieldTable(fields) {
+  const rows = fieldRows(fields);
+  return rows.length > 0
+    ? {
+        type: 'table',
+        headers: ['Field', 'Type', 'Required', 'Description'],
+        rows,
+      }
+    : null;
+}
+
+/**
+ * One self-doc as a topic section, keyed by the doc's own name.
+ * @param {any} doc
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
+ */
+export function selfDocSection(doc) {
+  /** @type {any[]} */
+  const content = [{type: 'prose', text: doc.description}];
+  if (doc.appliesTo) {
+    content.push({type: 'prose', text: `Applies to: ${doc.appliesTo}`});
+  }
+  const table = schemaFieldTable(doc.fields ?? []);
+  if (table) content.push(table);
+  for (const example of doc.examples ?? []) {
+    if (typeof example?.code !== 'string' || example.code.trim() === '')
+      continue;
+    content.push({
+      type: 'code',
+      lang: example.lang ?? 'js',
+      ...(example.label ? {label: example.label} : {}),
+      code: example.code,
+    });
+  }
+  for (const note of doc.notes ?? []) {
+    if (TOPIC_BLOCKS.has(note?.type)) content.push(note);
+  }
+  return {id: doc.name, title: doc.displayName ?? doc.name, content};
+}
+
+/**
+ * The `authoring` topic: one section per self-doc, in the order given.
+ * @param {any[]} docs
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceDoc}
+ */
+export function buildAuthoringReferenceDoc(docs) {
+  return /** @type {any} */ ({
+    name: 'authoring',
+    title: 'Authoring Reference',
+    category: 'guide',
+    description:
+      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type.',
+    sections: docs.map(selfDocSection),
+  });
+}
+
+/**
+ * The `authoring` topic from every self-doc that loads. One that fails is left
+ * out here and reported by {@link auditAuthoringSelfDocs}.
+ * @returns {Promise<import('../../authoring/doctypes/reference/type').ReferenceDoc>}
+ */
+export async function buildAuthoringTopic() {
+  const {loaded} = await loadAuthoringSelfDocs();
+  return buildAuthoringReferenceDoc(loaded.map(entry => entry.doc));
+}
+
+/**
+ * What stands between a self-doc and a reader of `astryx docs authoring`.
+ * @param {{root?: string, sources?: string[], budget?: number}} [options]
+ * @returns {Promise<{
+ *   sections: number,
+ *   unreachable: string[],
+ *   failed: {source: string, error: string}[],
+ *   oversized: {key: string, title: string, bytes: number}[],
+ * }>}
+ */
+export async function auditAuthoringSelfDocs({
+  root = AUTHORING_ROOT,
+  sources = AUTHORING_SELF_DOCS,
+  budget = DOC_OUTPUT_BUDGET_BYTES,
+} = {}) {
+  const listed = new Set(sources);
+  const unreachable = discoverAuthoringSelfDocSources(root).filter(
+    source => !listed.has(source),
+  );
+  const {loaded, failed} = await loadAuthoringSelfDocs(sources, root);
+  const topic = buildAuthoringReferenceDoc(loaded.map(entry => entry.doc));
+  return {
+    sections: topic.sections.length,
+    unreachable,
+    failed,
+    oversized: oversizedDocSections(topic.sections, budget),
+  };
+}