An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file Provider resolution — one resolver and one package identity for every
* path that decides which integration package contributes under a provider ID.
*
* Project resolves configured, then autolinked, then local packages here.
* `upgrade` resolves the same set plus its own candidates here, under the
* codemod policy. `markProviderConflicts` is a wrapper over the same conflict
* pass. Besides the resolved list, every resolution returns a ledger with
* exactly one outcome for every package directory it was handed, so no
* candidate can leave the list without a record.
*
* Identity is the real package directory. `name@version` labels an entry for
* display. It also decides whether two DIFFERENT directories hold one published
* package (an npm alias installed as a copy), because precedence has always
* treated those as one package, but it never keys the ledger.
*
* @input Candidates in precedence order, each a loaded integration record or a
* load failure, tagged with the source that reached it; a policy.
* @output The resolved LoadedIntegration list, and the ledger keyed by real
* package directory.
* @position foundation/integrations — the only place precedence is decided;
* callers load packages, this module picks winners.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
/**
* @typedef {import('./integrations.mjs').LoadedIntegration} LoadedIntegration
*/
/**
* Where a candidate came from. Precedence follows candidate order; the source
* selects which rules apply.
* - `configured`: named by astryx.config; listed even when its manifest fails
* - `autolinked`: a declared dependency that ships one root manifest
* - `local`: the package being authored, loaded from its working bytes
* - `installed`: codemod policy — the installed copy of a package being
* authored that lists itself
* - `extra`: codemod policy — a package named with `upgrade --integration`
* @typedef {'configured' | 'autolinked' | 'local' | 'installed' | 'extra'} CandidateSource
*/
/**
* One package reached by one input. A candidate without `integration` failed
* to load (`error`) or reached a directory an earlier candidate already
* reached (`repeat`).
* @typedef {object} ProviderCandidate
* @property {CandidateSource} source
* @property {LoadedIntegration} [integration]
* @property {string} [spec] the input that reached the package
* @property {string} [packageDir] required when `integration` is absent
* @property {string} [error] why loading threw
* @property {boolean} [repeat] another input for a directory already reached
*/
/**
* @typedef {'contributes' | 'set-aside' | 'load-failed' | 'alias-of'} ProviderOutcome
*/
/**
* Why a package is set aside.
* - `claimed-earlier`: a package earlier in precedence claims its provider ID
* - `authored-claims`: the package being authored claims its provider ID
* - `replaced-by-authored`: it is the installed copy of the package being
* authored, whose working bytes are used instead
* - `installed-stands-in`: codemod policy — the package being authored is
* represented by its installed copy
* @typedef {'claimed-earlier' | 'authored-claims' | 'replaced-by-authored' | 'installed-stands-in'} SetAsideReason
*/
/**
* The one outcome for one real package directory.
* @typedef {object} ProviderLedgerEntry
* @property {string} key real package directory
* @property {string} label `name@version`, for display only
* @property {ProviderOutcome} outcome
* @property {ProviderCandidate} candidate the candidate this outcome belongs to
* @property {ProviderCandidate[]} refs every candidate that reached this
* directory, in order
* @property {string} [providerId]
* @property {string} [winner] set-aside: key of the package used instead
* @property {SetAsideReason} [reason] set-aside: why
* @property {string} [aliasOf] alias-of: key of the package this one repeats
* @property {LoadedIntegration} [integration] the record this package left in
* the resolved list, when it left one
* @property {string} [error] load-failed: the load error
*/
/** @typedef {Map<string, ProviderLedgerEntry>} ProviderLedger */
/**
* @typedef {object} ProviderPolicy
* @property {boolean} [codemods] upgrade's codemod rule. Candidates are an
* already resolved Project list plus `installed` and `extra` candidates. The
* installed copy stands in for a package being authored that lists itself or
* is named as an extra, and an extra stands in for the autolinked package it
* repeats. Autolinked and local packages still claim provider IDs, but they
* are not listed: upgrade has never run their codemods.
* @property {ProviderLedger} [prior] the ledger this resolution builds on. A
* record it already set aside keeps that winner, and its entries this
* resolution never reaches are carried over unchanged.
*/
/**
* @typedef {object} CandidateState
* @property {ProviderCandidate} candidate
* @property {LoadedIntegration | undefined} record
* @property {string} key
* @property {ProviderOutcome} [outcome]
* @property {CandidateState} [winner]
* @property {SetAsideReason} [reason]
* @property {CandidateState} [aliasOf]
* @property {LoadedIntegration} [listed]
*/
/**
* @typedef {object} Slot
* @property {CandidateState} state
* @property {LoadedIntegration} record
*/
/** Lower wins when several candidates reach one directory. */
const OUTCOME_RANK = /** @type {const} */ ({
contributes: 0,
'set-aside': 1,
'load-failed': 2,
'alias-of': 3,
});
/**
* The identity of a package directory: its real path, so every symlinked
* spelling of one pnpm store entry is one package.
* @param {string} packageDir
* @returns {string}
*/
export function packageKey(packageDir) {
try {
return fs.realpathSync(packageDir);
} catch {
return path.resolve(packageDir);
}
}
/**
* @param {ProviderCandidate} candidate
* @param {number} index
* @returns {string}
*/
function candidateKey(candidate, index) {
const dir = candidate.integration?.__packageDir ?? candidate.packageDir;
// Only a hand-built record lacks a directory; it is its own package.
return typeof dir === 'string' && dir.length > 0
? packageKey(dir)
: `#${index}`;
}
/**
* 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
);
}
/**
* The display label of a package: `name@version`, plus the spec that reached
* it when that differs from the name.
* @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.',
},
};
}
/**
* `name@version`, the display label of a package.
* @param {LoadedIntegration} integration
* @returns {string}
*/
function packageLabel(integration) {
return integration.version
? `${integration.name}@${integration.version}`
: integration.name;
}
/**
* One published package at one version. Two directories that share it hold
* the same package; it never keys the ledger.
* @param {LoadedIntegration} integration
* @returns {string}
*/
function publishedIdentity(integration) {
return `${integration.name}\u0000${integration.version ?? ''}`;
}
/**
* @param {CandidateState} state
* @param {ProviderOutcome} outcome
* @param {Partial<Pick<CandidateState, 'winner' | 'reason' | 'aliasOf' | 'listed'>>} [detail]
*/
function settle(state, outcome, detail = {}) {
state.outcome = outcome;
state.winner = detail.winner;
state.reason = detail.reason;
state.aliasOf = detail.aliasOf;
state.listed = detail.listed;
}
/**
* Project precedence: configured packages in config order, then autolinked
* packages that do not repeat one already loaded, then the package being
* authored, which replaces the first entry with its name.
* @param {CandidateState[]} states
* @returns {Slot[]}
*/
function assembleProject(states) {
/** @type {Slot[]} */
const slots = [];
// Published identities of configured entries and of kept autolinked ones.
/** @type {Map<string, CandidateState>} */
const loaded = new Map();
for (const state of states) {
const {candidate, record} = state;
if (candidate.repeat) {
settle(state, 'alias-of');
continue;
}
if (candidate.source === 'autolinked') {
// A dependency the project never named cannot fail its load, so a
// broken one is recorded here and listed nowhere.
if (record == null || record.__loadError != null) {
settle(state, 'load-failed');
continue;
}
const repeated = loaded.get(publishedIdentity(record));
if (repeated != null) {
settle(state, 'alias-of', {aliasOf: repeated});
continue;
}
loaded.set(publishedIdentity(record), state);
slots.push({state, record});
continue;
}
if (candidate.source === 'local' && record != null) {
const replaced = slots.findIndex(
slot => slot.record?.name === record.name,
);
if (replaced === -1) {
slots.push({state, record});
} else {
settle(slots[replaced].state, 'set-aside', {
winner: state,
reason: 'replaced-by-authored',
});
slots[replaced] = {state, record};
}
continue;
}
if (record != null && typeof record === 'object') {
const identity = publishedIdentity(record);
if (!loaded.has(identity)) loaded.set(identity, state);
}
slots.push({state, record: /** @type {LoadedIntegration} */ (record)});
}
return slots;
}
/**
* Upgrade precedence under the codemod policy, over an already resolved
* Project list: configured packages (the installed copy in place of a package
* being authored that lists itself), then claimants, then extras.
* @param {CandidateState[]} states
* @returns {{slots: Slot[], claimants: CandidateState[]}}
*/
function assembleCodemods(states) {
const configured = states.filter(
state => state.candidate.source === 'configured' && !state.candidate.repeat,
);
const installed = states.filter(
state => state.candidate.source === 'installed',
);
const extras = states.filter(state => state.candidate.source === 'extra');
const local = states.find(
state => state.record?.__local && !state.candidate.repeat,
);
const selfListed = local != null && configured.includes(local);
/** @type {CandidateState[]} */
const participants = [...configured];
if (local != null && selfListed && installed.length > 0) {
participants.splice(participants.indexOf(local), 1, ...installed);
settle(local, 'set-aside', {
winner: installed[0],
reason: 'installed-stands-in',
});
}
const namedLocal =
local == null
? undefined
: extras.find(extra => extra.record?.name === local.record?.name);
const localStandsIn = local != null && (selfListed || namedLocal != null);
if (local != null && !selfListed && namedLocal != null) {
settle(local, 'set-aside', {
winner: namedLocal,
reason: 'installed-stands-in',
});
}
/** @type {Map<string, CandidateState>} */
const extraIdentities = new Map();
for (const extra of extras) {
if (extra.record == null) continue;
const identity = publishedIdentity(extra.record);
if (!extraIdentities.has(identity)) extraIdentities.set(identity, extra);
}
/** @type {CandidateState[]} */
const claimants = [];
for (const state of states) {
const {candidate, record} = state;
if (candidate.repeat || record == null) continue;
const claimant =
candidate.source === 'autolinked' ||
(candidate.source === 'local' && !localStandsIn);
if (!claimant) continue;
const named = extraIdentities.get(publishedIdentity(record));
if (named != null) {
settle(state, 'alias-of', {aliasOf: named});
continue;
}
claimants.push(state);
}
for (const state of states) {
if (state.candidate.repeat) settle(state, 'alias-of');
}
const slots = [...participants, ...claimants, ...extras].map(state => ({
state,
record: /** @type {LoadedIntegration} */ (state.record),
}));
return {slots, claimants};
}
/**
* The provider-ID pass over assembled entries. The package being authored
* claims first; everything else claims in order. A later claimant that is the
* same published package as the winner is the same package reached twice and
* loads once; any other later claimant becomes an inert conflict record.
* @param {Slot[]} slots
* @returns {LoadedIntegration[]}
*/
function markConflicts(slots) {
/** @type {Map<string, Slot>} */
const claims = new Map();
for (const slot of slots) {
if (slot.record?.__local && claimsProvider(slot.record)) {
const providerId = /** @type {string} */ (slot.record.providerId);
if (!claims.has(providerId)) claims.set(providerId, slot);
}
}
/** @type {LoadedIntegration[]} */
const resolved = [];
for (const slot of slots) {
const {state, record} = slot;
if (!claimsProvider(record)) {
resolved.push(record);
if (record?.__providerConflict != null) {
settle(state, 'set-aside', {listed: record});
} else if (record == null || record.__loadError != null) {
settle(state, 'load-failed', {listed: record});
} else {
settle(state, 'contributes', {listed: record});
}
continue;
}
const providerId = /** @type {string} */ (record.providerId);
const claimant = claims.get(providerId);
if (claimant == null) {
claims.set(providerId, slot);
resolved.push(record);
settle(state, 'contributes', {listed: record});
} else if (claimant.record === record) {
resolved.push(record);
settle(state, 'contributes', {listed: record});
} else if (
claimant.record.name !== record.name ||
claimant.record.version !== record.version
) {
const conflict = providerConflict(record, claimant.record);
resolved.push(conflict);
settle(state, 'set-aside', {
winner: claimant.state,
reason: claimant.record.__local ? 'authored-claims' : 'claimed-earlier',
listed: conflict,
});
} else {
settle(state, 'alias-of', {aliasOf: claimant.state});
}
}
return resolved;
}
/**
* Fold candidate outcomes into one entry per real package directory. A
* directory reached by several candidates keeps the strongest outcome among
* them; every candidate stays listed in `refs`.
* @param {CandidateState[]} states
* @param {ProviderLedger | undefined} prior
* @param {Set<LoadedIntegration>} listed records in the final list
* @returns {ProviderLedger}
*/
function buildLedger(states, prior, listed) {
/** @type {Map<string, CandidateState>} */
const chosen = new Map();
/** @type {Map<string, ProviderCandidate[]>} */
const refs = new Map();
for (const state of states) {
const current = chosen.get(state.key);
const outcome = state.outcome ?? 'load-failed';
if (
current == null ||
OUTCOME_RANK[outcome] < OUTCOME_RANK[current.outcome ?? 'load-failed']
) {
chosen.set(state.key, state);
}
const list = refs.get(state.key) ?? [];
list.push(state.candidate);
refs.set(state.key, list);
}
/** @type {ProviderLedger} */
const ledger = new Map();
for (const [key, state] of chosen) {
const {candidate, record} = state;
const outcome = state.outcome ?? 'load-failed';
const previous = prior?.get(key);
/** @type {ProviderLedgerEntry} */
const entry = {
key,
label:
record != null && typeof record === 'object' && record.name
? packageLabel(record)
: (candidate.spec ?? key),
outcome,
candidate,
// A resolution on top of a prior ledger re-reads that ledger's records;
// only its own new inputs join the inputs already recorded there.
refs:
previous == null
? (refs.get(key) ?? [candidate])
: [
...previous.refs,
...(refs.get(key) ?? []).filter(
ref => ref.source === 'installed' || ref.source === 'extra',
),
],
};
if (record?.providerId != null) entry.providerId = record.providerId;
if (outcome === 'set-aside') {
const winner = state.winner?.key ?? previous?.winner;
if (winner != null) entry.winner = winner;
const reason = state.reason ?? previous?.reason;
if (reason != null) entry.reason = reason;
}
if (outcome === 'alias-of') entry.aliasOf = state.aliasOf?.key ?? key;
if (state.listed != null && listed.has(state.listed)) {
entry.integration = state.listed;
}
const error = record?.__loadError ?? candidate.error;
if (outcome === 'load-failed' && error != null) entry.error = error;
ledger.set(key, entry);
}
for (const [key, entry] of prior ?? []) {
if (!ledger.has(key)) ledger.set(key, entry);
}
return ledger;
}
/**
* Resolve provider identity over candidates in precedence order.
*
* Returns the resolved integration list every command reads, and a ledger
* with one outcome for every real package directory among the candidates:
* `contributes`, `set-aside` (with the winner and a reason), `load-failed`, or
* `alias-of` (the same published package already loaded from another
* directory, or another input for a directory already reached).
*
* @param {ProviderCandidate[]} candidates in precedence order
* @param {ProviderPolicy} [policy]
* @returns {{integrations: LoadedIntegration[], ledger: ProviderLedger}}
*/
export function resolveProviders(candidates, policy = {}) {
/** @type {CandidateState[]} */
const states = candidates.map((candidate, index) => ({
candidate,
record: candidate.integration,
key: candidateKey(candidate, index),
}));
/** @type {LoadedIntegration[]} */
let integrations;
if (policy.codemods) {
const {slots, claimants} = assembleCodemods(states);
const resolved = markConflicts(slots);
// Claimants leave by package directory: the pass can hand one back as a
// new conflict record, and upgrade must not report a package every other
// command uses as set aside.
const claimantDirs = new Set(
claimants.map(state => state.record?.__packageDir),
);
integrations = resolved.filter(
integration =>
integration.__packageDir == null ||
!claimantDirs.has(integration.__packageDir),
);
} else {
integrations = markConflicts(assembleProject(states));
}
const ledger = buildLedger(states, policy.prior, new Set(integrations));
return {integrations, ledger};
}