@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.ddb63c3

package/foundation/integrations/provider-resolution.test.mjs

@@ -0,0 +1,369 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for the provider resolver: one outcome per real package
+ * directory, precedence, and the wrappers that keep their old results.
+ *
+ * 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 {packageKey, resolveProviders} from './provider-resolution.mjs';
+import {markProviderConflicts} from './integrations.mjs';
+import {autolinkIntegrations} from './autolink.mjs';
+import {Project, providerLedgerOf} from '../config/project.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-provider-resolution-'),
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * A loaded-integration record in a real directory.
+ * @param {string} dir directory under the temp root
+ * @param {Record<string, unknown>} fields
+ * @returns {any}
+ */
+function record(dir, fields) {
+  const packageDir = path.join(tmpDir, dir);
+  fs.mkdirSync(packageDir, {recursive: true});
+  return {
+    providerId: fields.name,
+    __spec: fields.name,
+    __packageDir: packageDir,
+    __manifestFile: path.join(packageDir, 'astryx.integration.mjs'),
+    ...fields,
+  };
+}
+
+/**
+ * @param {string} source
+ * @param {any} integration
+ */
+const candidate = (source, integration) => ({
+  source,
+  integration,
+  spec: integration.__spec,
+});
+
+/** @param {Map<string, any>} ledger */
+function outcomes(ledger) {
+  return [...ledger.values()].map(entry => [entry.label, entry.outcome]);
+}
+
+describe('resolveProviders ledger', () => {
+  it('records one outcome for every candidate, keyed by real directory', () => {
+    const widgets = record('widgets', {
+      name: '@acme/widgets',
+      version: '1.0.0',
+    });
+    const renamed = record('renamed', {
+      name: '@acme/renamed',
+      version: '2.0.0',
+      providerId: '@acme/widgets',
+    });
+    const broken = record('broken', {
+      name: '@acme/broken',
+      version: '1.0.0',
+      __loadError: 'boom',
+    });
+    const {integrations, ledger} = resolveProviders([
+      candidate('configured', widgets),
+      candidate('configured', renamed),
+      candidate('configured', broken),
+    ]);
+
+    expect([...ledger.keys()]).toEqual(
+      [widgets, renamed, broken].map(entry => packageKey(entry.__packageDir)),
+    );
+    expect(outcomes(ledger)).toEqual([
+      ['@acme/widgets@1.0.0', 'contributes'],
+      ['@acme/renamed@2.0.0', 'set-aside'],
+      ['@acme/broken@1.0.0', 'load-failed'],
+    ]);
+    const setAside = ledger.get(packageKey(renamed.__packageDir));
+    expect(setAside).toMatchObject({
+      winner: packageKey(widgets.__packageDir),
+      reason: 'claimed-earlier',
+      integration: integrations[1],
+    });
+    expect(integrations[1].__providerConflict.claimedBy).toBe('@acme/widgets');
+  });
+
+  it('keeps two packages that share a name apart', () => {
+    const old = record('widgets-old', {
+      name: '@acme/widgets',
+      version: '1.0.0',
+      __spec: 'widgets-old',
+    });
+    const next = record('widgets-next', {
+      name: '@acme/widgets',
+      version: '2.0.0',
+      __spec: 'widgets-next',
+    });
+    const {ledger} = resolveProviders([
+      candidate('configured', old),
+      candidate('configured', next),
+    ]);
+
+    expect(outcomes(ledger)).toEqual([
+      ['@acme/widgets@1.0.0', 'contributes'],
+      ['@acme/widgets@2.0.0', 'set-aside'],
+    ]);
+  });
+
+  it('folds every spelling of one real directory into one entry', () => {
+    const ui = record('ui', {name: '@acme/ui', version: '0.1.22'});
+    const link = path.join(tmpDir, 'legacy-ui');
+    fs.symlinkSync(ui.__packageDir, link, 'dir');
+    const legacy = {...ui, __spec: '@acme/legacy-ui', __packageDir: link};
+    const {integrations, ledger} = resolveProviders([
+      candidate('configured', ui),
+      candidate('configured', legacy),
+    ]);
+
+    expect(integrations).toEqual([ui]);
+    expect([...ledger.keys()]).toEqual([packageKey(ui.__packageDir)]);
+    const [entry] = ledger.values();
+    expect(entry.outcome).toBe('contributes');
+    expect(entry.refs.map(ref => ref.spec)).toEqual([
+      '@acme/ui',
+      '@acme/legacy-ui',
+    ]);
+  });
+
+  it('records an autolinked copy of a loaded package as alias-of it', () => {
+    const ui = record('ui', {name: '@acme/ui', version: '0.1.22'});
+    const copy = record('legacy-ui', {
+      name: '@acme/ui',
+      version: '0.1.22',
+      __spec: '@acme/legacy-ui',
+      __autolinked: true,
+    });
+    const {integrations, ledger} = resolveProviders([
+      candidate('configured', ui),
+      candidate('autolinked', copy),
+    ]);
+
+    expect(integrations).toEqual([ui]);
+    expect(ledger.get(packageKey(copy.__packageDir))).toMatchObject({
+      outcome: 'alias-of',
+      aliasOf: packageKey(ui.__packageDir),
+    });
+  });
+
+  it('records an autolinked package that failed to load, and lists it nowhere', () => {
+    const packageDir = path.join(tmpDir, 'unreadable');
+    const {integrations, ledger} = resolveProviders([
+      {
+        source: 'autolinked',
+        spec: '@acme/unreadable',
+        packageDir,
+        error: 'bad json',
+      },
+    ]);
+
+    expect(integrations).toEqual([]);
+    expect(ledger.get(packageKey(packageDir))).toMatchObject({
+      outcome: 'load-failed',
+      error: 'bad json',
+    });
+  });
+
+  it('lets the package being authored replace its installed copy and claim first', () => {
+    const installed = record('installed', {
+      name: '@acme/widgets',
+      version: '1.0.0',
+    });
+    const rival = record('rival', {
+      name: '@acme/rival',
+      version: '1.0.0',
+      providerId: '@acme/widgets',
+    });
+    const local = record('local', {
+      name: '@acme/widgets',
+      version: '2.0.0-dev',
+      __local: true,
+    });
+    const {integrations, ledger} = resolveProviders([
+      candidate('configured', rival),
+      candidate('configured', installed),
+      candidate('local', local),
+    ]);
+
+    expect(integrations.map(entry => entry.name)).toEqual([
+      '@acme/rival',
+      '@acme/widgets',
+    ]);
+    expect(integrations[1]).toBe(local);
+    expect(ledger.get(packageKey(installed.__packageDir))).toMatchObject({
+      outcome: 'set-aside',
+      reason: 'replaced-by-authored',
+      winner: packageKey(local.__packageDir),
+    });
+    expect(ledger.get(packageKey(rival.__packageDir))).toMatchObject({
+      outcome: 'set-aside',
+      reason: 'authored-claims',
+      winner: packageKey(local.__packageDir),
+    });
+  });
+
+  it('keeps configured precedence ahead of autolinked', () => {
+    const configured = record('configured', {
+      name: '@acme/one',
+      version: '1.0.0',
+    });
+    const autolinked = record('autolinked', {
+      name: '@acme/two',
+      version: '1.0.0',
+      providerId: '@acme/one',
+      __autolinked: true,
+    });
+    const {ledger} = resolveProviders([
+      candidate('configured', configured),
+      candidate('autolinked', autolinked),
+    ]);
+
+    expect(outcomes(ledger)).toEqual([
+      ['@acme/one@1.0.0', 'contributes'],
+      ['@acme/two@1.0.0', 'set-aside'],
+    ]);
+  });
+
+  it('under the codemod policy, records the installed copy standing in', () => {
+    const local = record('local', {
+      name: '@acme/widgets',
+      version: '2.0.0-dev',
+      __local: true,
+    });
+    const installed = record('installed', {
+      name: '@acme/widgets',
+      version: '1.0.0',
+    });
+    const {integrations, ledger} = resolveProviders(
+      [candidate('configured', local), candidate('installed', installed)],
+      {codemods: true},
+    );
+
+    expect(integrations).toEqual([installed]);
+    expect(ledger.get(packageKey(local.__packageDir))).toMatchObject({
+      outcome: 'set-aside',
+      reason: 'installed-stands-in',
+      winner: packageKey(installed.__packageDir),
+    });
+  });
+});
+
+describe('markProviderConflicts', () => {
+  const a = {name: 'a', version: '1', providerId: 'x', __spec: 'a'};
+  const b = {name: 'b', version: '1', providerId: 'x', __spec: 'b'};
+  const alias = {name: 'a', version: '1', providerId: 'x', __spec: 'a-alias'};
+  const local = {
+    name: 'l',
+    version: '1',
+    providerId: 'x',
+    __spec: 'l',
+    __local: true,
+  };
+  /** @param {any[]} list */
+  const claimsOf = list =>
+    markProviderConflicts(list).map(entry => [
+      entry?.name ?? null,
+      entry?.__providerConflict?.claimedBy ?? null,
+    ]);
+
+  it('drops an alias of the winner and keeps a record listed twice', () => {
+    expect(claimsOf([a, b, alias, a, undefined])).toEqual([
+      ['a', null],
+      ['b', 'a'],
+      ['a', null],
+      [null, null],
+    ]);
+  });
+
+  it('lets the package being authored claim first', () => {
+    expect(claimsOf([a, undefined, b, alias, a, local])).toEqual([
+      ['a', 'l'],
+      [null, null],
+      ['b', 'l'],
+      ['a', 'l'],
+      ['a', 'l'],
+      ['l', null],
+    ]);
+  });
+});
+
+describe('Project.load keeps a ledger', () => {
+  /**
+   * @param {string} dir node_modules key
+   * @param {{name: string, version: string}} pkg
+   */
+  function install(dir, pkg) {
+    const pkgDir = path.join(tmpDir, 'node_modules', ...dir.split('/'));
+    fs.mkdirSync(pkgDir, {recursive: true});
+    fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify(pkg));
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    return pkgDir;
+  }
+
+  it('records the autolink alias it drops as alias-of the loaded copy', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({
+        name: 'consumer',
+        dependencies: {
+          '@acme/legacy-ui': 'npm:@acme/ui@0.1.22',
+          '@acme/ui': '0.1.22',
+        },
+      }),
+    );
+    const legacy = install('@acme/legacy-ui', {
+      name: '@acme/ui',
+      version: '0.1.22',
+    });
+    const ui = install('@acme/ui', {name: '@acme/ui', version: '0.1.22'});
+
+    const project = await Project.load(tmpDir, {fresh: true});
+    expect(project.loadedIntegrations.map(entry => entry.__spec)).toEqual([
+      '@acme/legacy-ui',
+    ]);
+    const ledger = providerLedgerOf(project);
+    expect(ledger.get(packageKey(ui))).toMatchObject({
+      outcome: 'alias-of',
+      aliasOf: packageKey(legacy),
+    });
+    expect(await autolinkIntegrations({projectDir: tmpDir})).toHaveLength(1);
+  });
+
+  it('records a dependency key that repeats a configured package', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'consumer', dependencies: {'@acme/ui': '0.1.22'}}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      "export default {integrations: ['@acme/ui']};\n",
+    );
+    const ui = install('@acme/ui', {name: '@acme/ui', version: '0.1.22'});
+
+    const ledger = providerLedgerOf(await Project.load(tmpDir, {fresh: true}));
+    expect([...ledger.keys()]).toEqual([packageKey(ui)]);
+    expect(ledger.get(packageKey(ui))?.refs.map(ref => ref.source)).toEqual([
+      'configured',
+      'autolinked',
+    ]);
+  });
+});

package/foundation/integrations/theme-descriptor.d.mts

@@ -0,0 +1,8 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @param {import('../../authoring/doctypes/theme/type.js').ThemeDoc} doc
+ * @returns {string}
+ */
+export function themeDescriptorSource(doc: import("../../authoring/doctypes/theme/type.js").ThemeDoc): string;

package/foundation/integrations/theme-descriptor.mjs

@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The source text of a typed integration theme descriptor.
+ *
+ * @input A theme's descriptor fields.
+ * @output The `.doc.mjs` source that declares them under their ThemeDoc type.
+ * @position Shared by `integration add theme`, which scaffolds a descriptor,
+ *   and the codemod that turns a 0.6 theme catalog into descriptors, so both
+ *   write the same bytes.
+ */
+
+/**
+ * A single-quoted JavaScript string literal for any text.
+ * @param {string} value
+ */
+function quote(value) {
+  const escaped = value
+    .replace(/\\/gu, '\\\\')
+    .replace(/'/gu, "\\'")
+    .replace(/\n/gu, '\\n')
+    .replace(/\r/gu, '\\r')
+    .replace(/\u2028/gu, '\\u2028')
+    .replace(/\u2029/gu, '\\u2029');
+  return `'${escaped}'`;
+}
+
+/**
+ * @param {import('../../authoring/doctypes/theme/type.js').ThemeDoc} doc
+ * @returns {string}
+ */
+export function themeDescriptorSource(doc) {
+  return [
+    "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */",
+    'export default {',
+    "  type: 'theme',",
+    `  name: ${quote(doc.name)},`,
+    `  displayName: ${quote(doc.displayName)},`,
+    `  description: ${quote(doc.description)},`,
+    `  maintained: ${doc.maintained},`,
+    '};',
+    '',
+  ].join('\n');
+}

package/foundation/integrations/validate-contributions.mjs

@@ -25,6 +25,23 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {isValidSemver} from '../env/semver.mjs';
 import {findSourceOnlyCandidates} from './contribution-inventory.mjs';
+import {
+  CODEMOD_FILE_RE,
+  CODEMOD_SKIP_DIRS,
+  CODEMOD_TEST_RE,
+  createFixContext,
+  DOC_CANDIDATE_RE,
+  heldRootFix,
+  newComponentDocNote,
+  notACodemodFix,
+  notAComponentFix,
+  readContributionStamp,
+  sharedCodemodsRootFix,
+  stampOf,
+  themeImporting,
+  TEMPLATE_CANDIDATE_RE,
+} from './contribution-fixes.mjs';
+import {MANIFEST_BASENAMES} from './integrations.mjs';
 import {discoverIntegrationCodemods} from '../../assets/codemods/integration-discovery.mjs';
 import {discoverIntegrationTemplatesForOne} from '../discovery/template-adapter.mjs';
 import * as componentDiscovery from '../discovery/component-discovery.mjs';
@@ -119,32 +136,82 @@ function checkRoots(resolved, issues) {
  */
 async function checkCodemods(integration, issues) {
   if (!integration.codemods || !fs.existsSync(integration.codemods)) return;
+  const context = integration.__packageDir
+    ? createFixContext(integration.__packageDir, integration)
+    : null;
+  const shared = context && sharedCodemodsRootFix(context);
   for (const entry of fs.readdirSync(integration.codemods, {
     withFileTypes: true,
   })) {
     if (
       entry.isFile() &&
-      /\.(?:ts|mjs|js)$/u.test(entry.name) &&
-      !/\.(?:test|spec|fixture)\.(?:ts|mjs|js)$/u.test(entry.name)
+      CODEMOD_FILE_RE.test(entry.name) &&
+      !CODEMOD_TEST_RE.test(entry.name) &&
+      // The manifest sits beside package.json and is never a codemod.
+      !(
+        integration.codemods === integration.__packageDir &&
+        MANIFEST_BASENAMES.includes(entry.name)
+      )
     ) {
+      const shown = path
+        .relative(
+          integration.__packageDir ?? path.dirname(integration.codemods),
+          path.join(integration.codemods, entry.name),
+        )
+        .split(path.sep)
+        .join('/');
+      const root = path.dirname(shown);
+      const full = path.join(integration.codemods, entry.name);
+      const stamp =
+        context &&
+        (DOC_CANDIDATE_RE.test(entry.name) ||
+          TEMPLATE_CANDIDATE_RE.test(entry.name))
+          ? stampOf(context, full)
+          : null;
+      // A theme's entry module may sit beside its descriptor.
+      const themeDoc = ['.doc.mjs', '.doc.ts', '.doc.js']
+        .map(suffix => full.replace(/\.(?:ts|mjs|js)$/u, suffix))
+        .find(candidate => candidate !== full && fs.existsSync(candidate));
+      const themeStamp =
+        context && !stamp && themeDoc ? stampOf(context, themeDoc) : null;
+      let fix = `Fix: move it into the folder named for the version it migrates to, for example ${root}/1.2.0/${entry.name}.`;
+      if (shared) fix = sharedCodemodsRootFix(context, entry.name) ?? fix;
+      else if (context && stamp) fix = notACodemodFix(context, full, stamp);
+      else if (context && themeDoc && themeStamp?.type === 'theme') {
+        fix = notACodemodFix(context, themeDoc, themeStamp, entry.name);
+      } else if (context) {
+        const owner = themeImporting(context, full);
+        if (owner) {
+          fix = notACodemodFix(
+            context,
+            owner.doc,
+            owner.stamp,
+            owner.source,
+            entry.name,
+          );
+        }
+      }
       issues.push(
         issueWarning(
           'codemod_outside_version',
-          `Codemod file "${path.join(integration.codemods, entry.name)}" is outside a version folder, so upgrade will never load it.`,
+          `Codemod file "${shown}" is outside a version folder, so upgrade will never load it. ${fix}`,
         ),
       );
     }
     if (
       entry.isDirectory() &&
-      !['node_modules', '.git', '__tests__', '__fixtures__'].includes(
-        entry.name,
-      ) &&
+      !CODEMOD_SKIP_DIRS.has(entry.name) &&
       !isValidSemver(entry.name)
     ) {
+      const fix =
+        shared ??
+        (context &&
+          heldRootFix(context, path.join(integration.codemods, entry.name))) ??
+        'Fix: rename it to the exact version its codemods migrate to.';
       issues.push(
         issueError(
           'invalid_codemod_version',
-          `Codemod folder "${entry.name}" is not an exact semver version such as 1.2.0.`,
+          `Codemod folder "${entry.name}" is not an exact semver version such as 1.2.0. ${fix}`,
         ),
       );
     }
@@ -196,24 +263,51 @@ async function checkComponents(integration, issues) {
   if (typeof discover !== 'function') return; // feature not present yet
   try {
     const records = (await discover(integration)) ?? [];
+    /** @type {import('./contribution-fixes.mjs').FixContext | undefined} */
+    let context;
     for (const record of records) {
       if (record?.sourcePath == null) {
+        const docPath = record?.docPath;
+        let fix = `Fix: add ${record?.name}.tsx beside ${docPath ? path.basename(docPath) : `${record?.name}.doc.mjs`}.`;
+        const stamp = docPath ? readContributionStamp(docPath, false) : null;
+        if (stamp && stamp.type !== 'component' && integration.__packageDir) {
+          context ??= createFixContext(integration.__packageDir, integration);
+          fix = notAComponentFix(context, docPath, stamp);
+        }
         issues.push(
           issueError(
             'invalid_component',
-            `Component "${record?.name}" is missing its same-stem source file ${record?.name}.tsx.`,
+            `Component "${record?.name}" is missing its same-stem source file ${record?.name}.tsx. ${fix}`,
           ),
         );
       }
     }
+    const overlap = integration.__packageDir
+      ? newComponentDocNote(
+          (context ??= createFixContext(integration.__packageDir, integration)),
+        )
+      : '';
     for (const name of findSourceOnlyCandidates(
       integration.components,
       records.map(record => record.name),
     )) {
+      // A hidden doc still pairs with its source; discovery just skips it.
+      if (
+        ['.doc.ts', '.doc.mjs', '.doc.js'].some(suffix =>
+          fs.existsSync(
+            path.join(
+              /** @type {string} */ (integration.components),
+              `${name}${suffix}`,
+            ),
+          ),
+        )
+      ) {
+        continue;
+      }
       issues.push(
         issueWarning(
           'source_without_component_doc',
-          `Component source "${name}.tsx" has no same-stem metadata file ${name}.doc.mjs, so Astryx ignores it.`,
+          `Component source "${name}.tsx" has no same-stem metadata file ${name}.doc.mjs, so Astryx ignores it. Fix: add ${name}.doc.mjs beside it with type: 'component'; \`astryx docs authoring component-doc\` lists its fields.${overlap}`,
         ),
       );
     }
@@ -250,7 +344,7 @@ async function checkDocs(integration, issues) {
 }
 
 /**
- * Validate the integration's source-theme catalog. The same discovery function
+ * Validate the integration's source-theme descriptors. The same discovery function
  * powers Project and theme list/add, so validation cannot accept a shape that
  * consumers later fail to use.
  * @param {LoadedIntegration} integration

package/foundation/response/error-codes.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'enum',
   name: 'error-codes',
   displayName: 'Error Codes',
-  namespace: 'cli',
+  namespace: 'cli/api',
   description:
     'Stable, append-only machine-readable error codes on the --json error envelope (envelope.code). Codes never change or get removed; branch on these, not on prose.',
   members: [
@@ -203,7 +203,7 @@ export const doc = {
     {
       value: 'ERR_THEME_INVALID',
       description:
-        'A theme definition or contributed theme catalog is invalid.',
+        'A theme definition or contributed theme descriptor is invalid.',
     },
     {
       value: 'ERR_THEME_LOAD',

package/foundation/response/error-codes.mjs

@@ -185,7 +185,7 @@ export const ERROR_CODES = Object.freeze({
   ERR_WRITE_FAILED: 'ERR_WRITE_FAILED',
 
   // ── Theme build ──────────────────────────────────────────────────
-  /** A theme definition or contributed theme catalog is invalid. */
+  /** A theme definition or contributed theme descriptor is invalid. */
   ERR_THEME_INVALID: 'ERR_THEME_INVALID',
   /** A theme file could not be loaded / parsed into a defineTheme result. */
   ERR_THEME_LOAD: 'ERR_THEME_LOAD',

package/foundation/response/response-types.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'enum',
   name: 'response-types',
   displayName: 'Response Types',
-  namespace: 'cli',
+  namespace: 'cli/api',
   description:
     'The `type` discriminant present on every --json success envelope. Consumers switch on it to narrow `data`.',
   members: [

package/foundation/response/response.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'schema',
   name: 'output',
   displayName: 'Output Envelope',
-  namespace: 'cli',
+  namespace: 'cli/api',
   description:
     'The single JSON envelope every command emits under --json. Success is ' +
     '{ apiVersion, type, data, meta? }; failure is { apiVersion, error, code, ' +