@pipeline-builder/pipeline-data 4.1.15 → 4.1.16

package/lib/api/plugin-resolution.d.ts

@@ -0,0 +1,253 @@
+import type { CrudTx } from './crud-service.js';
+import { type AdvisorySeverity, type BlockedListingRef, type BlockOnAdvisory, type OfficialInstalls, type PluginAdvisory, type PluginInstall, type PluginInstallPolicy, type PluginListing, type PluginListingVersion, type Publisher, type PublisherTier } from '../database/drizzle-schema.js';
+/** An org's consumption policy, as the resolver applies it. */
+export interface ConsumptionPolicy {
+    allowedTiers: PublisherTier[];
+    requireApprovalTiers: PublisherTier[];
+    secretsAllowedTiers: PublisherTier[];
+    blockOnAdvisory: BlockOnAdvisory;
+    officialInstalls: OfficialInstalls;
+    blockedListings: BlockedListingRef[];
+}
+/** The defaults (and the column defaults of `plugin_install_policies`). */
+export declare const DEFAULT_CONSUMPTION_POLICY: Readonly<ConsumptionPolicy>;
+/** At most this many blocked listings per policy. */
+export declare const MAX_BLOCKED_LISTINGS = 500;
+/** A stored policy row (or none) as a {@link ConsumptionPolicy}. */
+export declare function policyOf(row: Partial<PluginInstallPolicy> | null | undefined): ConsumptionPolicy;
+/**
+ * A team's policy under its root org's: each field takes the STRICTER of
+ * the two, so a team can narrow what its root allows but never widen it.
+ */
+export declare function mergeConsumptionPolicies(root: ConsumptionPolicy, team: ConsumptionPolicy): ConsumptionPolicy;
+/**
+ * The policy an org's resolution runs under. A root org: its own row (or the
+ * defaults). A team (`rootOrgId` set): its root's policy, merged with the
+ * team's own row when it has one.
+ */
+export declare function effectiveConsumptionPolicy(rows: ReadonlyArray<Partial<PluginInstallPolicy> & {
+    orgId?: string;
+}>, orgId: string, rootOrgId?: string): ConsumptionPolicy;
+/**
+ * Validate a (partial) policy update over `base`. Returns the full new policy,
+ * or an error message. `blockedListings` entries are `{ publisher, name }` or
+ * `"publisher/name"`.
+ */
+export declare function applyPolicyUpdate(base: ConsumptionPolicy, input: unknown): ConsumptionPolicy | string;
+/** Why a reference can't resolve; `code` is an api-core `ErrorCode` name. */
+export interface ResolutionRefusal {
+    code: 'NOT_FOUND' | 'PLUGIN_NOT_INSTALLED' | 'PLUGIN_BLOCKED_BY_POLICY' | 'PLUGIN_UNAVAILABLE';
+    reason: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/** A non-fatal note a resolution carries (synth prints it). */
+export interface ResolutionWarning {
+    code: 'PLUGIN_ADVISORY' | 'PLUGIN_DEPRECATED' | 'PLUGIN_SECRETS_WITHHELD' | 'LISTING_UNMAINTAINED';
+    message: string;
+}
+/** Why the org's policy (or the listing's state) keeps a listing out, or null. */
+export interface ListingBlock {
+    reason: 'tier' | 'blocked_listing' | 'suspended';
+    message: string;
+}
+/** Whether `policy` (or the listing's own state) refuses the listing outright. */
+export declare function listingBlock(policy: ConsumptionPolicy, publisher: Pick<Publisher, 'handle' | 'tier' | 'suspendedAt'>, listing: Pick<PluginListing, 'name' | 'state'>): ListingBlock | null;
+/** The refusal a {@link ListingBlock} becomes. */
+export declare function blockRefusal(block: ListingBlock): ResolutionRefusal;
+/** Severities each `blockOnAdvisory` setting blocks. */
+export declare const ADVISORY_BLOCK_SEVERITIES: Readonly<Record<BlockOnAdvisory, readonly AdvisorySeverity[]>>;
+/**
+ * Whether an advisory's `affectedRange` covers `version`: `||`-separated
+ * comparator sets, each either the lookup spec forms (`^`, `~`, partial,
+ * exact) or space-separated comparators (`>=1.0.0 <1.2.3`) or a hyphen range.
+ * `*` covers everything; an unparseable range covers nothing.
+ */
+export declare function advisoryRangeCovers(range: string, version: string): boolean;
+/**
+ * Why `range` isn't a usable advisory range (the forms {@link advisoryRangeCovers}
+ * understands), or null when it is. An advisory whose range parses as nothing
+ * would silently cover nothing, so drafts are refused instead.
+ */
+export declare function advisoryRangeProblem(range: string): string | null;
+/** The PUBLISHED advisories whose range covers `version` (any severity), most severe first. */
+export declare function advisoriesCovering<A extends Pick<PluginAdvisory, 'severity' | 'state' | 'affectedRange'>>(advisories: readonly A[], version: string): A[];
+/** The PUBLISHED advisories the policy blocks `version` for. */
+export declare function blockingAdvisories(advisories: readonly Pick<PluginAdvisory, 'id' | 'severity' | 'state' | 'affectedRange' | 'fixedVersion' | 'summary'>[], version: string, policy: Pick<ConsumptionPolicy, 'blockOnAdvisory'>): Array<Pick<PluginAdvisory, 'id' | 'severity' | 'state' | 'affectedRange' | 'fixedVersion' | 'summary'>>;
+/** How the org reaches a listing: an explicit install row, or the implicit Official one. */
+export type InstallMode = {
+    kind: 'explicit';
+    install: PluginInstall;
+    inherited: boolean;
+} | {
+    kind: 'implicit';
+};
+type VersionRow = Pick<PluginListingVersion, 'version' | 'yankedAt' | 'pausedAt' | 'breaking'>;
+/**
+ * The implicit Official install's range: every version of the LOWEST live
+ * major (`<major>.x`) — patch and minor versions flow, a new major never does
+ * (the org moves to it with an explicit install). Null when nothing is live.
+ */
+export declare function implicitInstallRange(versions: readonly VersionRow[]): string | null;
+/** Whether an install's version policy admits `version` (the baseline is `pinnedVersion`). */
+export declare function installAdmits(install: Pick<PluginInstall, 'versionPolicy' | 'pinnedVersion'>, version: string, versions: readonly VersionRow[]): boolean;
+/** Whether `mode` admits `version` (the implicit range for an implicit install). */
+export declare function modeAdmits(mode: InstallMode, version: string, versions: readonly VersionRow[]): boolean;
+/** Input to {@link selectListingVersion}. */
+export interface VersionChoiceInput<V extends PluginListingVersion = PluginListingVersion> {
+    ref: string;
+    versions: readonly V[];
+    mode: InstallMode;
+    /** The reference's own version spec (`filter.version`). */
+    requested?: string;
+    advisories: readonly PluginAdvisory[];
+    policy: ConsumptionPolicy;
+}
+/**
+ * Pick the listed version a reference resolves to (see the module doc), or
+ * the refusal that explains why none can.
+ */
+export declare function selectListingVersion<V extends PluginListingVersion>(input: VersionChoiceInput<V>): {
+    version: V;
+} | {
+    refusal: ResolutionRefusal;
+};
+/** The org (and, for a team, its root org) a resolution runs for. */
+export interface ResolutionScope {
+    orgId: string;
+    /** The root org when the caller is a team. */
+    rootOrgId?: string;
+}
+/** The org ids whose installs and policies apply, own first. */
+export declare function scopeOrgIds(scope: ResolutionScope): string[];
+/**
+ * How the org reaches `listing` — or the refusal. An ACTIVE own-org row wins,
+ * then the root org's (a team inherits it); failing both, the implicit
+ * Official install (unless the policy is `explicit`); otherwise the org's own
+ * pending / denied row explains the refusal.
+ */
+export declare function installModeFor(publisher: Pick<Publisher, 'handle'>, listing: Pick<PluginListing, 'id' | 'name'>, installs: readonly PluginInstall[], policy: ConsumptionPolicy, scope: ResolutionScope): InstallMode | ResolutionRefusal;
+/** The rows the resolver reads. Implementations must run with a scope that can
+ *  read the ecosystem tables and the org's (and root org's) install rows. */
+export interface ListingDataSource {
+    publisherByHandle(handle: string): Promise<Publisher | null>;
+    publishersByIds(ids: string[]): Promise<Publisher[]>;
+    listingByName(publisherId: string, name: string): Promise<PluginListing | null>;
+    /** Listed / unmaintained listings (optionally only these ids or names). */
+    liveListings(filter?: {
+        ids?: string[];
+        names?: string[];
+    }): Promise<PluginListing[]>;
+    versionsForListings(listingIds: string[]): Promise<PluginListingVersion[]>;
+    /** PUBLISHED advisories. */
+    advisoriesForListings(listingIds: string[]): Promise<PluginAdvisory[]>;
+    installsForOrgs(orgIds: string[]): Promise<PluginInstall[]>;
+    policiesForOrgs(orgIds: string[]): Promise<PluginInstallPolicy[]>;
+}
+/**
+ * A {@link ListingDataSource} over a drizzle transaction. The caller owns the
+ * transaction's scope: it must be able to read the ecosystem tables (app-role
+ * RLS) and the install rows of the org AND its root org (a team's reads of its
+ * root's rows need an elevated scope, like parent-org plugin reads).
+ */
+export declare function drizzleListingSource(tx: CrudTx): ListingDataSource;
+/** A plugin reference as the resolver reads it. */
+export interface ListingReference {
+    /** Publisher handle; absent = the Official listing (the unqualified fallback). */
+    publisher?: string;
+    name: string;
+    /** The reference's `filter.version`. */
+    version?: string;
+}
+/** A reference that resolved to a listed version. */
+export interface ListingResolved {
+    ok: true;
+    publisher: Publisher;
+    listing: PluginListing;
+    version: PluginListingVersion;
+    mode: InstallMode;
+    policy: ConsumptionPolicy;
+    /** The spec declares secrets the policy withholds from this tier. */
+    secretsWithheld: boolean;
+    warnings: ResolutionWarning[];
+}
+/** A reference that named a listing but can't resolve. */
+export interface ListingRefused {
+    ok: false;
+    refusal: ResolutionRefusal;
+    publisher?: Publisher;
+    listing?: PluginListing;
+}
+/**
+ * Resolve `ref` to a listed version for `scope`, or refuse. Null when the
+ * listing doesn't exist at all (an unqualified reference then simply has no
+ * Official fallback).
+ */
+export declare function resolveListingReference(source: ListingDataSource, ref: ListingReference, scope: ResolutionScope): Promise<ListingResolved | ListingRefused | null>;
+/**
+ * The non-fatal notes a resolved listed version carries (lookup answers,
+ * synth prints them, the installs view shows them): an unmaintained listing, a
+ * deprecated version, a PUBLISHED advisory covering the version that the org's
+ * `blockOnAdvisory` doesn't block (a blocking one refuses resolution instead),
+ * and withheld secrets.
+ */
+export declare function listedVersionWarnings(input: {
+    publisher: Pick<Publisher, 'handle' | 'tier'>;
+    listing: Pick<PluginListing, 'name' | 'state'>;
+    version: Pick<PluginListingVersion, 'version' | 'deprecatedAt' | 'deprecationMessage' | 'specSnapshot'>;
+    advisories: readonly Pick<PluginAdvisory, 'severity' | 'state' | 'affectedRange' | 'fixedVersion' | 'summary'>[];
+    policy: Pick<ConsumptionPolicy, 'secretsAllowedTiers'>;
+}): {
+    warnings: ResolutionWarning[];
+    secretsWithheld: boolean;
+};
+/**
+ * The plugin record a resolved listing version runs as — the shape synth and
+ * the contract check read (a `plugins` row's run fields), built from the
+ * version's frozen spec snapshot. `id` is the LISTING VERSION's id (the step
+ * manifest resolves it back), `imageRepository` its `public/*` copy.
+ */
+export declare function listedPluginRecord(res: ListingResolved): Record<string, unknown>;
+/** One listing with the org's standing on it. */
+export interface OrgListingState {
+    publisher: Publisher;
+    listing: PluginListing;
+    versions: PluginListingVersion[];
+    /** How the org reaches it, or why it can't (not installed, pending, …). */
+    mode: InstallMode | ResolutionRefusal;
+    /** A policy / state block (tier, blocked listing, suspended), or null. */
+    block: ListingBlock | null;
+    /** What an UNVERSIONED reference resolves to right now, or null. */
+    resolved: PluginListingVersion | null;
+    /** Why nothing resolves, when the org does reach the listing (e.g. an advisory block). */
+    refusal: ResolutionRefusal | null;
+    /** The listing's PUBLISHED advisories. */
+    advisories: PluginAdvisory[];
+    /** The org's own install row for it (explicit, possibly pending/denied). */
+    ownInstall: PluginInstall | null;
+    /** The org's effective consumption policy (the same for every listing). */
+    policy: ConsumptionPolicy;
+}
+/** The org's policy + install rows (own and root). */
+export interface OrgInstallContext {
+    policy: ConsumptionPolicy;
+    installs: PluginInstall[];
+    scope: ResolutionScope;
+}
+/** Load the org's policy and install rows. */
+export declare function loadOrgInstallContext(source: ListingDataSource, scope: ResolutionScope): Promise<OrgInstallContext>;
+/**
+ * The org's standing on every live listing (or only `filter`'s). Used by the
+ * in-app catalog; {@link resolvableListings} narrows it to what resolves.
+ */
+export declare function orgListingStates(source: ListingDataSource, scope: ResolutionScope, filter?: {
+    ids?: string[];
+    names?: string[];
+}, ctx?: OrgInstallContext): Promise<OrgListingState[]>;
+/** The listings an org's references resolve to now (installed or implicit, not blocked). */
+export declare function resolvableListings(source: ListingDataSource, scope: ResolutionScope, filter?: {
+    names?: string[];
+}): Promise<Array<OrgListingState & {
+    resolved: PluginListingVersion;
+}>>;
+export {};