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

package/foundation/integrations/provider-resolution.d.mts

@@ -0,0 +1,152 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * 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: string): string;
+/**
+ * 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: ProviderCandidate[], policy?: ProviderPolicy): {
+    integrations: LoadedIntegration[];
+    ledger: ProviderLedger;
+};
+export type LoadedIntegration = import("./integrations.mjs").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`
+ */
+export type CandidateSource = "configured" | "autolinked" | "local" | "installed" | "extra";
+/**
+ * One package reached by one input. A candidate without `integration` failed
+ * to load (`error`) or reached a directory an earlier candidate already
+ * reached (`repeat`).
+ */
+export type ProviderCandidate = {
+    source: CandidateSource;
+    integration?: import("./integrations.mjs").LoadedIntegration | undefined;
+    /**
+     * the input that reached the package
+     */
+    spec?: string | undefined;
+    /**
+     * required when `integration` is absent
+     */
+    packageDir?: string | undefined;
+    /**
+     * why loading threw
+     */
+    error?: string | undefined;
+    /**
+     * another input for a directory already reached
+     */
+    repeat?: boolean | undefined;
+};
+export type ProviderOutcome = "contributes" | "set-aside" | "load-failed" | "alias-of";
+/**
+ * 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
+ */
+export type SetAsideReason = "claimed-earlier" | "authored-claims" | "replaced-by-authored" | "installed-stands-in";
+/**
+ * The one outcome for one real package directory.
+ */
+export type ProviderLedgerEntry = {
+    /**
+     * real package directory
+     */
+    key: string;
+    /**
+     * `name@version`, for display only
+     */
+    label: string;
+    outcome: ProviderOutcome;
+    /**
+     * the candidate this outcome belongs to
+     */
+    candidate: ProviderCandidate;
+    /**
+     * every candidate that reached this
+     * directory, in order
+     */
+    refs: ProviderCandidate[];
+    providerId?: string | undefined;
+    /**
+     * set-aside: key of the package used instead
+     */
+    winner?: string | undefined;
+    /**
+     * set-aside: why
+     */
+    reason?: SetAsideReason | undefined;
+    /**
+     * alias-of: key of the package this one repeats
+     */
+    aliasOf?: string | undefined;
+    /**
+     * the record this package left in
+     * the resolved list, when it left one
+     */
+    integration?: import("./integrations.mjs").LoadedIntegration | undefined;
+    /**
+     * load-failed: the load error
+     */
+    error?: string | undefined;
+};
+export type ProviderLedger = Map<string, ProviderLedgerEntry>;
+export type ProviderPolicy = {
+    /**
+     * 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.
+     */
+    codemods?: boolean | undefined;
+    /**
+     * 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.
+     */
+    prior?: ProviderLedger | undefined;
+};
+export type CandidateState = {
+    candidate: ProviderCandidate;
+    record: LoadedIntegration | undefined;
+    key: string;
+    outcome?: ProviderOutcome | undefined;
+    winner?: CandidateState | undefined;
+    reason?: SetAsideReason | undefined;
+    aliasOf?: CandidateState | undefined;
+    listed?: import("./integrations.mjs").LoadedIntegration | undefined;
+};
+export type Slot = {
+    state: CandidateState;
+    record: LoadedIntegration;
+};