@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/api/theme/add/add.rollback.test.mjs

@@ -1,158 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * `theme add` writes a theme as one transaction: when a later file fails to
- * publish, every file it already replaced gets its previous bytes back and
- * every file it created is removed. Publishing is forced to fail by wrapping
- * the two calls that publish a staged file: `linkSync` for a new file and
- * `renameSync` for a replacement.
- *
- * Separate file because vi.mock is hoisted and affects the whole module.
- */
-
-import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
-import * as os from 'node:os';
-import * as path from 'node:path';
-
-const failures = vi.hoisted(() => ({
-  /** Fail the Nth staged-file publish (1-based); 0 disables. */
-  publish: 0,
-  /** Also fail every rollback restore. */
-  restore: false,
-  count: 0,
-}));
-
-vi.mock('node:fs', async importOriginal => {
-  const actual = /** @type {typeof import('node:fs')} */ (
-    await importOriginal()
-  );
-  /** @param {string} source */
-  const isStaged = source => path.basename(String(source)).includes('.tmp');
-  /** @param {string} source */
-  const isRestore = source =>
-    path.basename(String(source)).includes('.restore-');
-  /** @param {string} source @param {string} op */
-  const maybeFail = (source, op) => {
-    if (isStaged(source) && failures.publish > 0) {
-      failures.count++;
-      if (failures.count === failures.publish) {
-        throw Object.assign(new Error(`EIO: forced ${op} failure`), {
-          code: 'EIO',
-        });
-      }
-    }
-    if (isRestore(source) && failures.restore) {
-      throw Object.assign(new Error(`EIO: forced restore failure`), {
-        code: 'EIO',
-      });
-    }
-  };
-  return {
-    ...actual,
-    linkSync: vi.fn((source, destination) => {
-      maybeFail(source, 'link');
-      return actual.linkSync(source, destination);
-    }),
-    renameSync: vi.fn((source, destination) => {
-      maybeFail(source, 'rename');
-      return actual.renameSync(source, destination);
-    }),
-  };
-});
-
-const fs = await import('node:fs');
-const {themeAdd} = await import('./add.mjs');
-const {listThemes} = await import('../_adapter.mjs');
-
-let tmpDir;
-
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-rollback-'));
-  failures.publish = 0;
-  failures.restore = false;
-  failures.count = 0;
-});
-
-afterEach(() => {
-  failures.publish = 0;
-  failures.restore = false;
-  fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-function stoneFiles() {
-  const theme = listThemes().find(entry => entry.slug === 'stone');
-  if (!theme) throw new Error('missing bundled theme stone');
-  expect(theme.files.length).toBeGreaterThanOrEqual(2);
-  return theme.files.map(name =>
-    path.join(tmpDir, 'src', 'themes', 'stone', name),
-  );
-}
-
-/** Entries staging or rollback left behind in the theme directory. */
-function strays() {
-  const dir = path.join(tmpDir, 'src', 'themes', 'stone');
-  if (!fs.existsSync(dir)) return [];
-  return fs
-    .readdirSync(dir, {recursive: true})
-    .map(String)
-    .filter(name => name.includes('.tmp') || name.includes('.restore-'));
-}
-
-describe('themeAdd rolls back a partial write', () => {
-  it('removes every created file when the second publish fails', async () => {
-    const files = stoneFiles();
-    failures.publish = 2;
-
-    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
-      code: 'ERR_WRITE_FAILED',
-    });
-
-    for (const file of files) expect(fs.existsSync(file)).toBe(false);
-    expect(strays()).toEqual([]);
-  });
-
-  it('restores every replaced byte when the second publish fails', async () => {
-    const files = stoneFiles();
-    fs.mkdirSync(path.dirname(files[0]), {recursive: true});
-    const before = Buffer.from([0x00, 0xff, 0x0a, 0x62, 0x65, 0x66]);
-    fs.writeFileSync(files[0], before);
-    failures.publish = 2;
-
-    await expect(
-      themeAdd('stone', {cwd: tmpDir, overwrite: true}),
-    ).rejects.toMatchObject({code: 'ERR_WRITE_FAILED'});
-
-    expect(fs.readFileSync(files[0]).equals(before)).toBe(true);
-    for (const file of files.slice(1)) expect(fs.existsSync(file)).toBe(false);
-    expect(strays()).toEqual([]);
-  });
-
-  it('names a file it could not restore', async () => {
-    const files = stoneFiles();
-    fs.mkdirSync(path.dirname(files[0]), {recursive: true});
-    fs.writeFileSync(files[0], 'before\n');
-    failures.publish = 2;
-    failures.restore = true;
-
-    let error;
-    try {
-      await themeAdd('stone', {cwd: tmpDir, overwrite: true});
-    } catch (caught) {
-      error = caught;
-    }
-
-    expect(error?.code).toBe('ERR_WRITE_FAILED');
-    expect(error?.message).toContain('Could not restore');
-    expect(error?.message).toContain(files[0]);
-  });
-
-  it('writes every file when nothing fails', async () => {
-    const files = stoneFiles();
-
-    const result = await themeAdd('stone', {cwd: tmpDir});
-
-    expect(result.type).toBe('theme.add');
-    for (const file of files) expect(fs.existsSync(file)).toBe(true);
-    expect(strays()).toEqual([]);
-  });
-});

package/api/theme/build/build.rollback.test.mjs

@@ -1,148 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * `theme build` writes its CSS, JS, and declarations as one transaction: when
- * a later output fails to publish, every output it already replaced gets its
- * previous bytes back and every output it created is removed. Publishing is
- * forced to fail by wrapping the two calls that publish a staged file:
- * `linkSync` for a new file and `renameSync` for a replacement.
- *
- * Separate file because vi.mock is hoisted and affects the whole module.
- * `themeBuild` needs a built core; the `node` project's globalSetup builds it.
- */
-
-import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
-import * as os from 'node:os';
-import * as path from 'node:path';
-
-const failures = vi.hoisted(() => ({
-  /** Fail the Nth staged-file publish (1-based); 0 disables. */
-  publish: 0,
-  count: 0,
-}));
-
-vi.mock('node:fs', async importOriginal => {
-  const actual = /** @type {typeof import('node:fs')} */ (
-    await importOriginal()
-  );
-  /** @param {string} source @param {string} op */
-  const maybeFail = (source, op) => {
-    if (!path.basename(String(source)).includes('.tmp')) return;
-    if (failures.publish === 0) return;
-    failures.count++;
-    if (failures.count === failures.publish) {
-      throw Object.assign(new Error(`EIO: forced ${op} failure`), {
-        code: 'EIO',
-      });
-    }
-  };
-  return {
-    ...actual,
-    linkSync: vi.fn((source, destination) => {
-      maybeFail(source, 'link');
-      return actual.linkSync(source, destination);
-    }),
-    renameSync: vi.fn((source, destination) => {
-      maybeFail(source, 'rename');
-      return actual.renameSync(source, destination);
-    }),
-  };
-});
-
-const fs = await import('node:fs');
-const {themeBuild} = await import('./build.mjs');
-
-vi.setConfig({testTimeout: 30000});
-
-let tmpDir;
-
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(
-    path.join(os.tmpdir(), 'astryx-theme-build-rollback-'),
-  );
-  failures.publish = 0;
-  failures.count = 0;
-});
-
-afterEach(() => {
-  failures.publish = 0;
-  fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-/**
- * Write a source for the theme named `rollbacktheme`. Each call uses a new
- * file so the loader cannot serve an earlier version from its cache.
- * @param {string} file @param {string} background
- */
-function writeTheme(file, background) {
-  fs.writeFileSync(
-    path.join(tmpDir, file),
-    `export default { name: 'rollbacktheme', tokens: { '--color-bg': '${background}' } };\n`,
-  );
-  return file;
-}
-
-const OUTPUTS = ['rollbacktheme.css', 'rollbacktheme.js', 'rollbacktheme.d.ts'];
-
-/** @returns {Map<string, Buffer | null>} */
-function readOutputs() {
-  return new Map(
-    OUTPUTS.map(name => {
-      const file = path.join(tmpDir, name);
-      return [name, fs.existsSync(file) ? fs.readFileSync(file) : null];
-    }),
-  );
-}
-
-function strays() {
-  return fs
-    .readdirSync(tmpDir)
-    .filter(name => name.includes('.tmp') || name.includes('.restore-'));
-}
-
-describe('themeBuild rolls back a partial write', () => {
-  it('removes every created output when the second publish fails', async () => {
-    const source = writeTheme('first.mjs', '#0a0a0a');
-    failures.publish = 2;
-
-    await expect(themeBuild(source, {}, {cwd: tmpDir})).rejects.toMatchObject({
-      code: 'ERR_WRITE_FAILED',
-    });
-
-    for (const bytes of readOutputs().values()) expect(bytes).toBeNull();
-    expect(strays()).toEqual([]);
-  });
-
-  it('restores every replaced output when the second publish fails', async () => {
-    const first = await themeBuild(
-      writeTheme('first.mjs', '#0a0a0a'),
-      {},
-      {cwd: tmpDir},
-    );
-    expect(first?.type).toBe('theme.build');
-    const before = readOutputs();
-    for (const bytes of before.values()) expect(bytes).not.toBeNull();
-
-    const next = writeTheme('next.mjs', '#fafafa');
-    failures.publish = 2;
-    await expect(themeBuild(next, {}, {cwd: tmpDir})).rejects.toMatchObject({
-      code: 'ERR_WRITE_FAILED',
-    });
-
-    const after = readOutputs();
-    for (const name of OUTPUTS) {
-      expect(
-        after.get(name)?.equals(/** @type {Buffer} */ (before.get(name))),
-      ).toBe(true);
-    }
-
-    // The failed build really had different bytes to write.
-    failures.publish = 0;
-    await themeBuild(next, {}, {cwd: tmpDir});
-    const css = readOutputs().get('rollbacktheme.css');
-    expect(
-      css?.equals(/** @type {Buffer} */ (before.get('rollbacktheme.css'))),
-    ).toBe(false);
-    expect(strays()).toEqual([]);
-  });
-});

package/api/upgrade/run/files-changed.test.mjs

@@ -1,111 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file The upgrade receipt counts a file once when a core codemod AND an
- * integration codemod both change it: `filesChanged` is the union of the two
- * runners' files, while `transformsApplied` adds their changes.
- *
- * Uses a real consumer under a repo-local temp dir (Vite blocks dynamic import
- * of config and integration modules from /tmp), the real core registry, and an
- * installed integration whose code codemod stamps the same file.
- */
-
-import {describe, it, expect, afterEach} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {upgrade} from '../upgrade.mjs';
-import {
-  latestVersion,
-  versions,
-  getTransformsBetween,
-} from '../../../assets/codemods/registry.mjs';
-
-const SLOW = 60_000;
-
-/** The registry version whose manifest ships the authoring migration. */
-async function authoringTier() {
-  const all = await getTransformsBetween('0.0.0', latestVersion);
-  const tier = all.find(({transforms}) =>
-    transforms.some(t => t.name === 'migrate-authoring-imports'),
-  );
-  if (!tier) throw new Error('no registry version ships the authoring migration');
-  return tier.version;
-}
-
-/**
- * A consumer with installed core at the registry's latest version and one
- * old-surface file that the core authoring codemods rewrite.
- * @param {string} dir
- * @param {{integrationCodemod: boolean}} options
- */
-function seed(dir, {integrationCodemod}) {
-  fs.writeFileSync(
-    path.join(dir, 'package.json'),
-    JSON.stringify({name: 'consumer', version: '1.0.0'}),
-  );
-  const core = path.join(dir, 'node_modules', '@astryxdesign', 'core');
-  fs.mkdirSync(core, {recursive: true});
-  fs.writeFileSync(
-    path.join(core, 'package.json'),
-    JSON.stringify({name: '@astryxdesign/core', version: latestVersion}),
-  );
-  fs.mkdirSync(path.join(dir, 'src'), {recursive: true});
-  fs.writeFileSync(
-    path.join(dir, 'src', 'Button.doc.mjs'),
-    [
-      "import {createComponentDoc} from '@astryxdesign/core/authoring';",
-      "export default createComponentDoc({name: 'Button', props: []});",
-      '',
-    ].join('\n'),
-  );
-  if (!integrationCodemod) return;
-  fs.writeFileSync(
-    path.join(dir, 'astryx.config.mjs'),
-    "export default {integrations: ['@acme/widgets']};\n",
-  );
-  const pkg = path.join(dir, 'node_modules', '@acme', 'widgets');
-  fs.mkdirSync(path.join(pkg, 'codemods', latestVersion), {recursive: true});
-  fs.writeFileSync(
-    path.join(pkg, 'package.json'),
-    JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
-  );
-  fs.writeFileSync(
-    path.join(pkg, 'astryx.integration.mjs'),
-    "export default {codemods: './codemods'};\n",
-  );
-  fs.writeFileSync(
-    path.join(pkg, 'codemods', latestVersion, 'acme-stamp.mjs'),
-    "export default {type: 'code', title: 'Stamp', transform: file => (file.source.includes('// acme') ? null : `${file.source}// acme\\n`)};\n",
-  );
-}
-
-describe('upgrade receipt — filesChanged across core and integration codemods', () => {
-  /** @type {string[]} */
-  const dirs = [];
-  afterEach(() => {
-    for (const dir of dirs.splice(0)) fs.rmSync(dir, {recursive: true, force: true});
-  });
-
-  /** @param {{integrationCodemod: boolean}} options */
-  async function run(options) {
-    const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-files-changed-'));
-    dirs.push(dir);
-    seed(dir, options);
-    const tier = await authoringTier();
-    const from = versions[versions.indexOf(tier) - 1];
-    const res = await upgrade({from, path: 'src'}, {cwd: dir});
-    expect(res.type).toBe('upgrade.run');
-    return res.data;
-  }
-
-  it('counts a file changed by both a core and an integration codemod once', async () => {
-    const coreOnly = await run({integrationCodemod: false});
-    expect(coreOnly.filesChanged).toBe(1);
-    expect(coreOnly.transformsApplied).toBeGreaterThan(0);
-
-    const both = await run({integrationCodemod: true});
-    expect(both.integrations).toEqual(['@acme/widgets']);
-    expect(both.filesChanged).toBe(1);
-    expect(both.transformsApplied).toBe(coreOnly.transformsApplied + 1);
-  }, SLOW);
-});

package/assets/codemods/file-count.test.mjs

@@ -1,163 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `filesChanged` counts FILES, not (codemod, file) pairs.
- *
- * One source file that four codemods each changed was reported as four files
- * changed — the total was incremented once per transform per file, so it
- * equalled `transformsApplied` in every run and the documented meaning of the
- * field ("Total files changed") was never true. The two numbers answer
- * different questions and both are in the receipt.
- */
-
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import jscodeshift from 'jscodeshift';
-import {runCodemods} from './runner.mjs';
-import {runIntegrationCodemods} from './integration-runner.mjs';
-
-let dir;
-
-beforeEach(() => {
-  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-file-count-'));
-});
-afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
-
-/** A transform that rewrites one distinctive token, so several can stack. */
-const renaming = (from, to) => (file) =>
-  file.source.includes(from) ? file.source.split(from).join(to) : null;
-
-/** @param {string} name @param {string[]} contents */
-function writeSources(...contents) {
-  return contents.map((content, i) => {
-    const file = path.join(dir, `file${i}.ts`);
-    fs.writeFileSync(file, content);
-    return file;
-  });
-}
-
-describe('core codemod runner — filesChanged counts files', () => {
-  it('reports 1 file for one file changed by four codemods', async () => {
-    writeSources('const a = ONE + TWO + THREE + FOUR;\n');
-
-    const result = await runCodemods(
-      [
-        {
-          version: '0.0.2',
-          transforms: [
-            {name: 'one', transform: renaming('ONE', '1'), meta: {title: 'one'}},
-            {name: 'two', transform: renaming('TWO', '2'), meta: {title: 'two'}},
-            {name: 'three', transform: renaming('THREE', '3'), meta: {title: 'three'}},
-            {name: 'four', transform: renaming('FOUR', '4'), meta: {title: 'four'}},
-          ],
-        },
-      ],
-      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
-    );
-
-    expect(result.totalTransformsApplied).toBe(4);
-    expect(result.totalFilesChanged).toBe(1);
-    expect(new Set(result.changedFiles).size).toBe(1);
-  });
-
-  it('still counts two files as two', async () => {
-    writeSources('const a = ONE;\n', 'const b = ONE;\n');
-
-    const result = await runCodemods(
-      [
-        {
-          version: '0.0.2',
-          transforms: [
-            {name: 'one', transform: renaming('ONE', '1'), meta: {title: 'one'}},
-          ],
-        },
-      ],
-      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
-    );
-
-    expect(result.totalTransformsApplied).toBe(2);
-    expect(result.totalFilesChanged).toBe(2);
-  });
-
-  it('reports 0 when nothing matched', async () => {
-    writeSources('const a = 1;\n');
-
-    const result = await runCodemods(
-      [
-        {
-          version: '0.0.2',
-          transforms: [
-            {name: 'one', transform: renaming('ONE', '1'), meta: {title: 'one'}},
-          ],
-        },
-      ],
-      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
-    );
-
-    expect(result.totalFilesChanged).toBe(0);
-    expect(result.totalTransformsApplied).toBe(0);
-  });
-});
-
-describe('integration codemod runner — filesChanged counts files', () => {
-  it('reports 1 file for one file changed by three integration codemods', () => {
-    writeSources('const a = ONE + TWO + THREE;\n');
-
-    const entry = (id, from, to) => ({
-      id,
-      package: '@acme/widgets',
-      type: 'code',
-      codemod: {title: id, transform: renaming(from, to)},
-    });
-
-    const result = runIntegrationCodemods(
-      [
-        {
-          version: '1.0.0',
-          codemods: [
-            entry('one', 'ONE', '1'),
-            entry('two', 'TWO', '2'),
-            entry('three', 'THREE', '3'),
-          ],
-        },
-      ],
-      {apply: true, path: dir, root: dir, skipCodemods: new Set(), jscodeshift, silent: true},
-    );
-
-    expect(result.totalTransformsApplied).toBe(3);
-    expect(result.totalFilesChanged).toBe(1);
-    expect(new Set(result.changedFiles).size).toBe(1);
-  });
-});
-
-describe('core codemod runner — a project codemod', () => {
-  it('counts every file it writes, and one change', async () => {
-    const result = await runCodemods(
-      [
-        {
-          version: '0.0.2',
-          transforms: [
-            {
-              name: 'project-plan',
-              meta: {title: 'project plan', codemodType: 'project'},
-              transform: async root => ({
-                writes: [
-                  {path: path.join(root, 'a.ts'), contents: 'a\n'},
-                  {path: path.join(root, 'b.ts'), contents: 'b\n'},
-                ],
-                deletes: [],
-                problems: [],
-              }),
-            },
-          ],
-        },
-      ],
-      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
-    );
-
-    expect(result.totalFilesChanged).toBe(2);
-    expect(result.totalTransformsApplied).toBe(1);
-  });
-});

package/assets/docs/tree/add-a-component.doc.mjs

@@ -1,75 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/components/add-a-component`: choose a
- * component name and generate its first source and doc files.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'add-a-component',
-  placement: {parent: 'namespace:components', slot: 'guides', order: 10},
-  title: 'Add a component',
-  category: 'guide',
-  description:
-    'Choose a stable component name and generate its source, doc, package export, and integration entry.',
-  sections: [
-    {
-      id: 'pick-a-component-name',
-      title: 'Pick a component name',
-      content: [
-        {
-          type: 'prose',
-          text: 'Choose a unique PascalCase name, such as `AcmeCarousel`. The name is the component\'s public export and CLI identity, so keep it stable. Use `displayName` when you only want to change the label people read.',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Prefer a name that describes the component\'s purpose in your product.',
-            'Avoid a Core component name unless you are deliberately replacing that component.',
-            'If replacement is truly required, read {@link generic:replace-a-core-component}.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'run-the-add-command',
-      title: 'Run the add command',
-      content: [
-        {
-          type: 'prose',
-          text: 'Run `integration add component` in your package with the name. It writes the component, its doc file, and the public import apps use.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx integration add component AcmeCarousel',
-        },
-        {
-          type: 'code',
-          lang: 'text',
-          code: `component contribution added
-
-[ok] AcmeCarousel
-
-Declare component root ./components in astryx.integration.mjs.
-
-- components/AcmeCarousel.doc.mjs
-- components/AcmeCarousel.tsx
-- package.json
-- astryx.integration.mjs`,
-        },
-        {
-          type: 'prose',
-          text: '`integration add` starts with one source export and one single-component `.doc.mjs`. Keep that shape for one public component. If the source exposes a family, choose the correct shape in {@link namespace:describe-the-component}.',
-        },
-        {
-          type: 'prose',
-          text: 'Add never overwrites a file, and `--dry-run` shows what it would write. Component commands read Core, so install `@astryxdesign/core` in the package first ({@link generic:quick-start}).',
-        },
-      ],
-    },
-  ],
-};