@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/foundation/integrations/integrations.mjs

@@ -29,6 +29,8 @@ import {
 } from '../../authoring/integration/schema.mjs';
 import {importUserModule, findPresentFiles} from '../fs/module-loader.mjs';
 import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
+import {parseDiscoverSource} from '../../authoring/discover/parse.mjs';
+import {resolveProviders} from './provider-resolution.mjs';
 
 /**
  * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
@@ -79,6 +81,9 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
  *   validated package-owned handler from the `gapReport` NAMED export.
  * @property {string} [__gapReportError] isolated named-handler validation error.
  *   Named exports are not manifest keys — see {@link loadManifest}.
+ * @property {import('../../authoring/discover/type').DiscoverSource} [__discover]
+ *   validated catalog source from the `discover` NAMED export.
+ * @property {string} [__discoverError] isolated discover-source validation error.
  */
 
 /** Conventional manifest basenames, in load-precedence order. */
@@ -116,107 +121,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;
 }
 
 /**
@@ -253,6 +171,23 @@ function parseGapReportHandlerExport(value, label) {
   }
 }
 
+/**
+ * Parse the optional named discover source the same way: a malformed one is
+ * isolated from every other contribution and reported by `astryx discover`.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {{source?: import('../../authoring/discover/type').DiscoverSource, error?: string}}
+ */
+function parseDiscoverSourceExport(value, label) {
+  if (value === undefined) return {};
+  try {
+    return {source: parseDiscoverSource(value, `${label} named export "discover"`)};
+  } catch (error) {
+    return {error: error instanceof Error ? error.message : String(error)};
+  }
+}
+
 /**
  * Load and validate a manifest module's default export, while isolating the
  * optional `agentDocs` contribution from the manifest's other fields.
@@ -269,7 +204,7 @@ function parseGapReportHandlerExport(value, label) {
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
  */
 export async function loadManifest(
   file,
@@ -280,6 +215,7 @@ export async function loadManifest(
   const raw = mod?.default;
   const baseManifest = parseIntegrationBase(raw, label);
   const gapReport = parseGapReportHandlerExport(mod?.gapReport, label);
+  const discover = parseDiscoverSourceExport(mod?.discover, label);
   const hasAgentDocs =
     raw != null &&
     typeof raw === 'object' &&
@@ -314,6 +250,8 @@ export async function loadManifest(
         : undefined,
     gapReport: gapReport.handler,
     gapReportError: gapReport.error,
+    discover: discover.source,
+    discoverError: discover.error,
     agentDocsError,
   };
 }
@@ -431,6 +369,10 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
   let gapReportHandler;
   /** @type {string | undefined} */
   let gapReportError;
+  /** @type {import('../../authoring/discover/type').DiscoverSource | undefined} */
+  let discoverSource;
+  /** @type {string | undefined} */
+  let discoverError;
   /** @type {string | undefined} */
   let agentDocsError;
   try {
@@ -440,6 +382,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
       debug: debugHandler,
       gapReport: gapReportHandler,
       gapReportError,
+      discover: discoverSource,
+      discoverError,
       agentDocsError,
     } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
   } catch (err) {
@@ -483,6 +427,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     __debug: debugHandler,
     __gapReport: gapReportHandler,
     __gapReportError: gapReportError,
+    __discover: discoverSource,
+    __discoverError: discoverError,
     __spec: spec,
     __packageDir: packageDir,
     __packageExports: pkg.exports ?? null,
@@ -534,6 +480,10 @@ export async function loadIntegrations(
     let gapReportHandler;
     /** @type {string | undefined} */
     let gapReportError;
+    /** @type {import('../../authoring/discover/type').DiscoverSource | undefined} */
+    let discoverSource;
+    /** @type {string | undefined} */
+    let discoverError;
     /** @type {string | undefined} */
     let agentDocsError;
     try {
@@ -543,6 +493,8 @@ export async function loadIntegrations(
         debug: debugHandler,
         gapReport: gapReportHandler,
         gapReportError,
+        discover: discoverSource,
+        discoverError,
         agentDocsError,
       } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
     } catch (err) {
@@ -593,6 +545,8 @@ export async function loadIntegrations(
       __debug: debugHandler,
       __gapReport: gapReportHandler,
       __gapReportError: gapReportError,
+      __discover: discoverSource,
+      __discoverError: discoverError,
       __spec: spec,
       __packageDir: packageDir,
       __packageExports: pkg.exports ?? null,

package/foundation/integrations/integrations.test.mjs

@@ -785,3 +785,34 @@ describe('the `gapReport` named export', () => {
     expect(loaded.__unknownKeys).toEqual(['gapReport']);
   });
 });
+
+describe('the `discover` named export', () => {
+  it('is carried out of the manifest module as __discover', async () => {
+    writeManifestPackage(tmpDir, {
+      body:
+        `export async function discover() { return {schemaVersion: 1}; }\n` +
+        `export default {issuesUrl: 'https://example.com/i'};\n`,
+    });
+
+    const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
+
+    expect(typeof loaded.__discover).toBe('function');
+    expect(loaded.__discoverError).toBeUndefined();
+    expect(loaded.__unknownKeys).toEqual([]);
+    expect(loaded.issuesUrl).toBe('https://example.com/i');
+  });
+
+  it('keeps the manifest and records why when the export is not a function', async () => {
+    writeManifestPackage(tmpDir, {
+      body:
+        `export const discover = {url: 'https://example.com/catalog.json'};\n` +
+        `export default {issuesUrl: 'https://example.com/i'};\n`,
+    });
+
+    const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
+
+    expect(loaded.__discover).toBeUndefined();
+    expect(loaded.__discoverError).toContain('must be a function');
+    expect(loaded.issuesUrl).toBe('https://example.com/i');
+  });
+});

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);
+});