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

package/foundation/integrations/contribution-inventory.d.mts

@@ -15,7 +15,7 @@
  */
 /**
  * Compute the files the tarball must contain for an integration's
- * contributions to be visible. Reads catalogs and walks directories;
+ * contributions to be visible. Walks descriptor-owned directories;
  * never imports or executes authored modules.
  *
  * @param {import('./integrations.mjs').LoadedIntegration} loaded

package/foundation/integrations/contribution-inventory.mjs

@@ -14,8 +14,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {isDeepStrictEqual} from 'node:util';
-import {THEME_MANIFEST_BASENAME} from '../discovery/theme-discovery.mjs';
-import {discoverIntegrationThemes} from '../discovery/theme-discovery.mjs';
+import {
+  discoverIntegrationThemes,
+  isThemeFolder,
+  listThemeFiles,
+} from '../discovery/theme-discovery.mjs';
 import {discoverIntegrationComponents} from '../discovery/component-discovery.mjs';
 import {loadComponentDoc} from '../discovery/component-loader.mjs';
 import {discoverIntegrationTemplatesForOne} from '../discovery/template-adapter.mjs';
@@ -65,27 +68,21 @@ function rel(packageDir, file) {
 
 /** @param {string} root @param {string} pkgDir */
 function enumerateThemeFiles(root, pkgDir) {
+  if (!root || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    return [];
+  }
+  // Exactly what `theme add` copies: each theme folder's files, including
+  // tests and fixtures, but no dot entry or file npm never publishes. Files
+  // beside the theme folders belong to no theme.
   /** @type {string[]} */
   const files = [];
-  const catalog = path.join(root, THEME_MANIFEST_BASENAME);
-  if (!fs.existsSync(catalog)) return files;
-  files.push(rel(pkgDir, catalog));
-  try {
-    const data = JSON.parse(fs.readFileSync(catalog, 'utf-8'));
-    if (data?.version !== 1 || !Array.isArray(data.themes)) return files;
-    for (const theme of data.themes) {
-      if (typeof theme.slug !== 'string' || !Array.isArray(theme.files))
-        continue;
-      for (const f of theme.files) {
-        if (typeof f === 'string') {
-          files.push(rel(pkgDir, path.join(root, theme.slug, f)));
-        }
-      }
+  for (const entry of fs.readdirSync(root, {withFileTypes: true})) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory() && isThemeFolder(full)) {
+      files.push(...listThemeFiles(full).map(file => path.join(full, file)));
     }
-  } catch {
-    /* Phase 1 catches structural issues */
   }
-  return files;
+  return files.sort().map(file => rel(pkgDir, file));
 }
 
 /** @param {string} root @param {string} pkgDir */
@@ -158,7 +155,7 @@ const ROOT_KINDS = /** @type {const} */ ([
 
 /**
  * Compute the files the tarball must contain for an integration's
- * contributions to be visible. Reads catalogs and walks directories;
+ * contributions to be visible. Walks descriptor-owned directories;
  * never imports or executes authored modules.
  *
  * @param {import('./integrations.mjs').LoadedIntegration} loaded

package/foundation/integrations/contribution-inventory.test.mjs

@@ -37,30 +37,37 @@ function loaded(overrides = {}) {
 
 function writeTheme(slug, files = [`${slug}Theme.ts`]) {
   const root = path.join(tmpDir, 'themes');
-  fs.mkdirSync(path.join(root, slug), {recursive: true});
-  for (const f of files) {
-    fs.writeFileSync(path.join(root, slug, f), `// ${f}\n`);
+  const themeDir = path.join(root, slug);
+  fs.mkdirSync(themeDir, {recursive: true});
+  for (const file of files) {
+    const target = path.join(themeDir, file);
+    fs.mkdirSync(path.dirname(target), {recursive: true});
+    fs.writeFileSync(target, `// ${file}\n`);
   }
-  const catalogPath = path.join(root, 'manifest.json');
-  let catalog = {version: 1, themes: []};
-  if (fs.existsSync(catalogPath)) {
-    catalog = JSON.parse(fs.readFileSync(catalogPath, 'utf-8'));
-  }
-  catalog.themes.push({
-    slug,
-    displayName: slug,
-    description: `${slug} theme.`,
-    maintained: true,
-    entry: files[0],
-    exportName: `${slug}Theme`,
-    files,
-  });
-  fs.writeFileSync(catalogPath, JSON.stringify(catalog, null, 2) + '\n');
+  fs.writeFileSync(
+    path.join(themeDir, `${slug}Theme.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: '${slug}', displayName: '${slug}', description: '${slug} theme.', maintained: true};\n`,
+  );
   return root;
 }
 
+const UNPUBLISHED = [
+  '.DS_Store',
+  '._oceanTheme.ts',
+  '.gitignore',
+  '.npmignore',
+  '.npmrc',
+  'oceanTheme.ts.orig',
+  'npm-debug.log',
+  'palette/.DS_Store',
+  'palette/npm-debug.log',
+  '.git/HEAD',
+  'CVS/Entries',
+  'node_modules/dep/index.js',
+];
+
 describe('computeRequiredFiles', () => {
-  it('enumerates manifest + theme catalog files', () => {
+  it('enumerates each complete descriptor-owned theme directory', () => {
     const root = writeTheme('ocean', ['oceanTheme.ts', 'tokens.ts']);
     const inv = computeRequiredFiles(loaded({themes: root}));
 
@@ -69,13 +76,46 @@ describe('computeRequiredFiles', () => {
     expect(inv.roots[0].kind).toBe('themes');
     expect(inv.roots[0].files).toEqual(
       expect.arrayContaining([
-        'themes/manifest.json',
+        'themes/ocean/oceanTheme.doc.mjs',
         'themes/ocean/oceanTheme.ts',
         'themes/ocean/tokens.ts',
       ]),
     );
     expect(inv.allFiles).toContain('astryx.integration.mjs');
-    expect(inv.allFiles).toContain('themes/manifest.json');
+    expect(inv.allFiles).toContain('themes/ocean/oceanTheme.doc.mjs');
+    expect(inv.allFiles).not.toContain('themes/manifest.json');
+  });
+
+  it('requires no file npm leaves out, at any depth, and none beside the themes', () => {
+    const root = writeTheme('ocean', ['oceanTheme.ts', 'palette/tokens.ts']);
+    for (const file of [
+      ...UNPUBLISHED.map(name => `ocean/${name}`),
+      'README.md',
+      'npm-debug.log',
+    ]) {
+      fs.mkdirSync(path.dirname(path.join(root, file)), {recursive: true});
+      fs.writeFileSync(path.join(root, file), 'x\n');
+    }
+    expect(computeRequiredFiles(loaded({themes: root})).roots[0].files).toEqual(
+      [
+        'themes/ocean/oceanTheme.doc.mjs',
+        'themes/ocean/oceanTheme.ts',
+        'themes/ocean/palette/tokens.ts',
+      ],
+    );
+  });
+
+  it('requires only the folders theme discovery reads', () => {
+    const root = writeTheme('ocean');
+    for (const file of ['shared/palette.ts', '.cache/state.json']) {
+      fs.mkdirSync(path.dirname(path.join(root, file)), {recursive: true});
+      fs.writeFileSync(path.join(root, file), '{}\n');
+    }
+    const inv = computeRequiredFiles(loaded({themes: root}));
+    expect(inv.roots[0].files).toEqual([
+      'themes/ocean/oceanTheme.doc.mjs',
+      'themes/ocean/oceanTheme.ts',
+    ]);
   });
 
   it('enumerates paired component metadata and source files', () => {
@@ -139,31 +179,31 @@ describe('computeRequiredFiles', () => {
     const root = path.join(tmpDir, 'templates');
     fs.mkdirSync(path.join(root, 'dashboard'), {recursive: true});
     fs.writeFileSync(
-      path.join(root, 'dashboard', 'dashboard.template.mjs'),
+      path.join(root, 'dashboard', 'dashboard.doc.mjs'),
       '// tmpl\n',
     );
     fs.writeFileSync(path.join(root, 'dashboard', 'dashboard.tsx'), '// src\n');
     const inv = computeRequiredFiles(loaded({templates: root}));
 
     expect(inv.roots[0].files).toContain(
-      'templates/dashboard/dashboard.template.mjs',
+      'templates/dashboard/dashboard.doc.mjs',
     );
     expect(inv.roots[0].files).toContain('templates/dashboard/dashboard.tsx');
   });
 
-  it('enumerates legacy .doc template metadata with paired sources', () => {
+  it('enumerates released .template compatibility metadata with paired sources', () => {
     const root = path.join(tmpDir, 'templates');
     fs.mkdirSync(path.join(root, 'dashboard'), {recursive: true});
     fs.writeFileSync(
-      path.join(root, 'dashboard', 'dashboard.doc.mjs'),
-      '// legacy template\n',
+      path.join(root, 'dashboard', 'dashboard.template.mjs'),
+      '// released compatibility template\n',
     );
     fs.writeFileSync(path.join(root, 'dashboard', 'dashboard.tsx'), '// src\n');
 
     const inv = computeRequiredFiles(loaded({templates: root}));
 
     expect(inv.roots[0].files).toEqual([
-      'templates/dashboard/dashboard.doc.mjs',
+      'templates/dashboard/dashboard.template.mjs',
       'templates/dashboard/dashboard.tsx',
     ]);
   });

package/foundation/integrations/integrations.d.mts

@@ -14,6 +14,9 @@
  * issues, Doctor, and the per-command warning name the one set aside instead of
  * dropping it without a word.
  *
+ * The conflict pass of {@link resolveProviders}, for a list that is already
+ * assembled.
+ *
  * @param {LoadedIntegration[]} integrations in precedence order
  * @returns {LoadedIntegration[]}
  */

package/foundation/integrations/integrations.mjs

@@ -29,6 +29,7 @@ import {
 } from '../../authoring/integration/schema.mjs';
 import {importUserModule, findPresentFiles} from '../fs/module-loader.mjs';
 import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
+import {resolveProviders} from './provider-resolution.mjs';
 
 /**
  * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
@@ -116,107 +117,20 @@ function providerIdForPackage(name) {
  * issues, Doctor, and the per-command warning name the one set aside instead of
  * dropping it without a word.
  *
+ * The conflict pass of {@link resolveProviders}, for a list that is already
+ * assembled.
+ *
  * @param {LoadedIntegration[]} integrations in precedence order
  * @returns {LoadedIntegration[]}
  */
 export function markProviderConflicts(integrations) {
-  /** @type {Map<string, LoadedIntegration>} */
-  const claims = new Map();
-  for (const integration of integrations) {
-    if (integration?.__local && claimsProvider(integration)) {
-      const providerId = /** @type {string} */ (integration.providerId);
-      if (!claims.has(providerId)) claims.set(providerId, integration);
-    }
-  }
-  /** @type {LoadedIntegration[]} */
-  const resolved = [];
-  for (const integration of integrations) {
-    if (!claimsProvider(integration)) {
-      resolved.push(integration);
-      continue;
-    }
-    const providerId = /** @type {string} */ (integration.providerId);
-    const claimant = claims.get(providerId);
-    if (claimant == null) {
-      claims.set(providerId, integration);
-      resolved.push(integration);
-    } else if (claimant === integration) {
-      resolved.push(integration);
-    } else if (
-      claimant.name !== integration.name ||
-      claimant.version !== integration.version
-    ) {
-      resolved.push(providerConflict(integration, claimant));
-    }
-  }
-  return resolved;
-}
-
-/**
- * Whether an entry contributes under its provider ID: it has one, its manifest
- * loaded, and it has not already been set aside.
- * @param {LoadedIntegration | undefined} integration
- * @returns {boolean}
- */
-function claimsProvider(integration) {
-  return (
-    integration?.providerId != null &&
-    integration.__loadError == null &&
-    integration.__providerConflict == null
-  );
-}
-
-/**
- * @param {LoadedIntegration} integration
- * @returns {string}
- */
-function describeIntegration(integration) {
-  const id = integration.version
-    ? `${integration.name}@${integration.version}`
-    : integration.name;
-  return integration.__spec && integration.__spec !== integration.name
-    ? `${id} (from "${integration.__spec}")`
-    : id;
-}
-
-/**
- * An inert record for a package whose provider ID is already claimed. It keeps
- * the package's identity and location for reporting, and drops every
- * contribution root and handler.
- * @param {LoadedIntegration} integration
- * @param {LoadedIntegration} claimant
- * @returns {LoadedIntegration}
- */
-function providerConflict(integration, claimant) {
-  const providerId =
-    /** @type {import('../../authoring/identity/type').ProviderId} */ (
-      integration.providerId
-    );
-  const winner = describeIntegration(claimant);
-  const setAside = describeIntegration(integration);
-  const reason = claimant.__local
-    ? 'is the package being authored, so it is used'
-    : 'loads first and is used';
-  return {
-    name: integration.name,
-    providerId,
-    version: integration.version,
-    __spec: integration.__spec,
-    __packageDir: integration.__packageDir,
-    __manifestFile: integration.__manifestFile,
-    ...(integration.__local ? {__local: true} : {}),
-    ...(integration.__autolinked
-      ? {__autolinked: true, __dependencyField: integration.__dependencyField}
-      : {}),
-    __providerConflict: {
-      providerId,
-      claimedBy: claimant.name,
-      message:
-        `${setAside} and ${winner} both claim provider ID "${providerId}". ` +
-        `${winner} ${reason}; ${setAside} contributes nothing ` +
-        'until one package changes its providerId.',
-    },
-  };
+  return resolveProviders(
+    integrations.map(integration => ({
+      source: /** @type {const} */ ('configured'),
+      integration,
+      spec: integration?.__spec,
+    })),
+  ).integrations;
 }
 
 /**

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

@@ -0,0 +1,275 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The provider ledger property: over seeded, generated projects, the
+ * real Project.load and the real `upgrade` context account for every candidate
+ * exactly once, and agree on the winner of every provider ID except where the
+ * codemod policy says otherwise.
+ *
+ * The expected candidates come from the scenario description, never from the
+ * resolver. Fixtures live under a repo-local temp dir, not /tmp, because Vite
+ * refuses to dynamically import a module from outside the project root.
+ */
+
+import {afterAll, beforeAll, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {Project, providerLedgerOf} from '../config/project.mjs';
+import {loadProjectContext} from '../../api/upgrade/_adapter.mjs';
+import {
+  expectedProjectInputs,
+  generateScenario,
+  isRunnable,
+  writeScenario,
+} from '../../test-utils/provider-scenarios.mjs';
+
+// 200 seeds keep this near 4 s; any seed range must hold.
+const SEEDS = Array.from({length: 200}, (_, index) => index + 1);
+const OUTCOMES = ['contributes', 'set-aside', 'load-failed', 'alias-of'];
+
+/** @type {string} */
+let root;
+/** @type {string} */
+let originalCwd;
+
+beforeAll(() => {
+  originalCwd = process.cwd();
+  root = fs.mkdtempSync(path.join(process.cwd(), '.astryx-provider-ledger-'));
+});
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/**
+ * The contributing package for each provider ID. Fails when two contribute
+ * under one ID.
+ * @param {Map<string, any>} ledger
+ * @returns {Map<string, any>}
+ */
+function winners(ledger) {
+  /** @type {Map<string, any>} */
+  const byProvider = new Map();
+  for (const entry of ledger.values()) {
+    if (entry.outcome !== 'contributes' || entry.providerId == null) continue;
+    expect(byProvider.has(entry.providerId)).toBe(false);
+    byProvider.set(entry.providerId, entry);
+  }
+  return byProvider;
+}
+
+/**
+ * Assert the ledger records one outcome for exactly the given inputs.
+ * @param {Map<string, any>} ledger
+ * @param {Array<{source: string, spec: string, key: string}>} inputs
+ */
+function expectAccounted(ledger, inputs) {
+  const refs = [...ledger.values()].flatMap(entry =>
+    entry.refs.map(ref => ({entry, ref})),
+  );
+  for (const input of inputs) {
+    const holders = refs.filter(
+      ({ref}) => ref.source === input.source && ref.spec === input.spec,
+    );
+    expect(holders.map(({entry}) => entry.key)).toEqual([input.key]);
+  }
+  expect(refs).toHaveLength(inputs.length);
+  expect(new Set(ledger.keys())).toEqual(
+    new Set(inputs.map(input => input.key)),
+  );
+  for (const [key, entry] of ledger) {
+    expect(entry.key).toBe(key);
+    expect(OUTCOMES).toContain(entry.outcome);
+    if (entry.outcome === 'set-aside') {
+      expect(ledger.has(entry.winner)).toBe(true);
+      expect(entry.reason).toEqual(expect.any(String));
+    }
+    if (entry.outcome === 'alias-of') {
+      expect(ledger.has(entry.aliasOf)).toBe(true);
+    }
+  }
+}
+
+describe('provider ledger over generated projects', () => {
+  it('accounts for every candidate once and agrees across Project and upgrade', async () => {
+    const coverage = {
+      scenarios: 0,
+      setAside: 0,
+      aliasOf: 0,
+      loadFailed: 0,
+      replaced: 0,
+      agreed: 0,
+      standIn: 0,
+      extraReordered: 0,
+    };
+
+    for (const seed of SEEDS) {
+      const scenario = generateScenario(seed);
+      if (!isRunnable(scenario)) continue;
+      coverage.scenarios++;
+      const dir = path.join(root, `seed-${seed}`);
+      fs.mkdirSync(dir);
+      writeScenario(dir, scenario);
+      const context = `seed ${seed}: ${JSON.stringify(scenario)}`;
+
+      const project = await Project.load(dir, {fresh: true});
+      const ledger = providerLedgerOf(project);
+      const inputs = expectedProjectInputs(dir, scenario);
+      try {
+        expectAccounted(ledger, inputs);
+
+        // Nothing leaves the list without a recorded reason.
+        const listed = new Set(project.loadedIntegrations);
+        for (const integration of project.loadedIntegrations) {
+          expect(ledger.has(fs.realpathSync(integration.__packageDir))).toBe(
+            true,
+          );
+        }
+        for (const entry of ledger.values()) {
+          if (entry.integration != null) {
+            expect(listed.has(entry.integration)).toBe(true);
+            continue;
+          }
+          expect(entry.outcome).not.toBe('contributes');
+          if (entry.outcome === 'set-aside') {
+            expect(entry.reason).toBe('replaced-by-authored');
+          }
+          if (entry.outcome === 'load-failed') {
+            expect(entry.error).toEqual(expect.any(String));
+          }
+        }
+      } catch (error) {
+        throw new Error(`${context}\n${error}`, {cause: error});
+      }
+
+      for (const entry of ledger.values()) {
+        if (entry.outcome === 'set-aside') coverage.setAside++;
+        if (entry.outcome === 'alias-of') coverage.aliasOf++;
+        if (entry.outcome === 'load-failed') coverage.loadFailed++;
+        if (entry.reason === 'replaced-by-authored') coverage.replaced++;
+      }
+
+      // `--integration` specs resolve from the process cwd.
+      process.chdir(dir);
+      const upgrade = await loadProjectContext(dir, scenario.extras);
+      process.chdir(originalCwd);
+
+      const modules = path.join(dir, 'node_modules');
+      /** @param {string} spec */
+      const installedKey = spec =>
+        fs.realpathSync(path.join(modules, ...spec.split('/')));
+      /** @param {string} spec */
+      const installedName = spec =>
+        JSON.parse(
+          fs.readFileSync(
+            path.join(modules, ...spec.split('/'), 'package.json'),
+            'utf8',
+          ),
+        ).name;
+      const configured = new Set(scenario.config ?? []);
+      const extras = [...new Set(scenario.extras)].filter(
+        spec => !configured.has(spec),
+      );
+      const {local} = scenario;
+      const localKey = fs.realpathSync(dir);
+      const selfListed = local != null && configured.has(local.name);
+      // The codemod policy: the installed copy stands in for the package being
+      // authored when it lists itself or is named with --integration.
+      const localStandsIn =
+        local != null &&
+        (selfListed || extras.some(spec => installedName(spec) === local.name));
+
+      try {
+        // Upgrade accounts for everything Project did, plus its own inputs.
+        expectAccounted(upgrade.ledger, [
+          ...inputs,
+          ...(selfListed
+            ? [
+                {
+                  source: 'installed',
+                  spec: local.name,
+                  key: installedKey(local.name),
+                },
+              ]
+            : []),
+          ...extras.map(spec => ({
+            source: 'extra',
+            spec,
+            key: installedKey(spec),
+          })),
+        ]);
+      } catch (error) {
+        throw new Error(`${context}\n${error}`, {cause: error});
+      }
+
+      const projectWinners = winners(ledger);
+      const upgradeWinners = winners(upgrade.ledger);
+      for (const providerId of new Set([
+        ...projectWinners.keys(),
+        ...upgradeWinners.keys(),
+      ])) {
+        const inProject = projectWinners.get(providerId);
+        const inUpgrade = upgradeWinners.get(providerId);
+        const same =
+          inProject != null &&
+          inUpgrade != null &&
+          (inProject.key === inUpgrade.key ||
+            upgrade.ledger.get(inProject.key)?.aliasOf === inUpgrade.key);
+        if (same) {
+          coverage.agreed++;
+          continue;
+        }
+        // The one documented exception, asserted explicitly: an installed
+        // copy took the authored package's place, so either upgrade's winner
+        // is an installed copy of that package, or Project's winner is the
+        // authored package it replaced.
+        const upgradeName =
+          inUpgrade?.integration?.name ??
+          inUpgrade?.candidate.integration?.name;
+        const standInWins =
+          localStandsIn && inUpgrade != null && upgradeName === local?.name;
+        const localReplaced =
+          localStandsIn && inProject != null && inProject.key === localKey;
+        // Project never saw an extra, so an ID only an extra claims has no
+        // Project winner to agree with.
+        const extraOnly =
+          inProject == null && inUpgrade?.candidate.source === 'extra';
+        // Known disagreement, pinned by the `it.fails` repros in
+        // api/upgrade/provider-agreement.test.mjs: upgrade replaces an
+        // autolinked winner with any extra of the same name@version, from
+        // any directory, and orders it with the extras. Another extra can
+        // then win, or nothing does, in upgrade only.
+        const projectWinnerInUpgrade =
+          inProject == null ? undefined : upgrade.ledger.get(inProject.key);
+        const repeatedByExtra =
+          projectWinnerInUpgrade != null &&
+          (projectWinnerInUpgrade.refs.some(ref => ref.source === 'extra') ||
+            (projectWinnerInUpgrade.outcome === 'alias-of' &&
+              upgrade.ledger
+                .get(projectWinnerInUpgrade.aliasOf)
+                ?.refs.some(ref => ref.source === 'extra')));
+        const extraReordered =
+          inProject?.candidate.source === 'autolinked' && repeatedByExtra;
+        if (extraReordered) {
+          coverage.extraReordered++;
+          continue;
+        }
+        expect(
+          standInWins || localReplaced || extraOnly,
+          `${context}\nprovider ${providerId}: Project ${inProject?.label ?? 'none'} vs upgrade ${inUpgrade?.label ?? 'none'}`,
+        ).toBe(true);
+        if (standInWins || localReplaced) coverage.standIn++;
+      }
+    }
+
+    // The generator must keep reaching every shape, or the property is vacuous.
+    expect(coverage.scenarios).toBeGreaterThanOrEqual(190);
+    expect(coverage.setAside).toBeGreaterThan(0);
+    expect(coverage.aliasOf).toBeGreaterThan(0);
+    expect(coverage.loadFailed).toBeGreaterThan(0);
+    expect(coverage.replaced).toBeGreaterThan(0);
+    expect(coverage.agreed).toBeGreaterThan(0);
+    expect(coverage.standIn).toBeGreaterThan(0);
+  }, 120_000);
+});