@pipeline-builder/pipeline-data 4.1.18 → 4.1.19

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

@@ -1,3 +1,37 @@
+/**
+ * Resolving a plugin reference to an ecosystem LISTING version through the
+ * org's install (docs/plugin-installing.md).
+ *
+ * One implementation shared by every place that answers "which listed version
+ * does this org's reference run?": the plugin service's `/plugins/lookup` (what
+ * synth pins), the pipeline service's contract check at pipeline create, the AI
+ * generator's plugin list and the placeholder guard. The decisions are PURE
+ * functions over loaded rows; the rows come through a {@link ListingDataSource}
+ * so each service can load them its own way ({@link drizzleListingSource} is the
+ * plain drizzle one).
+ *
+ * The model:
+ *  - An org resolves a listing only through an INSTALL: an explicit
+ *    `plugin_installs` row (its own, or — for a team — its root org's), or
+ *    for the Official publisher the IMPLICIT install every org has unless its
+ *    consumption policy says `officialInstalls: explicit`. An explicit
+ *    install overrides the implicit one.
+ *  - The org's CONSUMPTION POLICY is applied at every resolution: allowed
+ *    tiers, blocked listings, advisory blocking; secrets are withheld from tiers
+ *    the policy doesn't trust with them. A team's policy is merged with its root
+ *    org's and can only be stricter.
+ *  - Version choice: the install's range (pinned / `~` / `^` / non-breaking
+ *    latest; implicit = the lowest live major), narrowed by the reference's own
+ *    version spec. Yanked versions never resolve for a listing; a paused
+ *    version is skipped unless the install already resolved to it or the
+ *    reference pins it exactly; advisory-blocked versions are skipped.
+ *  - Scan flags: a version the nightly rescan FLAGGED (fixable Criticals
+ *    over `PLUGIN_VULN_MAX_CRITICAL`) resolves with a `VULN_FLAGGED` warning —
+ *    or, with `PLUGIN_BLOCK_ON_NEW_CRITICAL` on, is skipped like an
+ *    advisory-blocked one, and an exact pin to it is refused
+ *    `PLUGIN_VERSION_VULN_BLOCKED`.
+ */
+import { type VulnFlaggedWarning } from '@pipeline-builder/api-core';
 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. */
@@ -36,16 +70,16 @@ export declare function effectiveConsumptionPolicy(rows: ReadonlyArray<Partial<P
 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';
+    code: 'NOT_FOUND' | 'PLUGIN_NOT_INSTALLED' | 'PLUGIN_BLOCKED_BY_POLICY' | 'PLUGIN_UNAVAILABLE' | 'PLUGIN_VERSION_VULN_BLOCKED';
     reason: string;
     message: string;
     details?: Record<string, unknown>;
 }
-/** A non-fatal note a resolution carries (synth prints it). */
-export interface ResolutionWarning {
+/** A non-fatal note a resolution carries (synth prints its `message`). */
+export type ResolutionWarning = {
     code: 'PLUGIN_ADVISORY' | 'PLUGIN_DEPRECATED' | 'PLUGIN_SECRETS_WITHHELD' | 'LISTING_UNMAINTAINED';
     message: string;
-}
+} | VulnFlaggedWarning;
 /** Why the org's policy (or the listing's state) keeps a listing out, or null. */
 export interface ListingBlock {
     reason: 'tier' | 'blocked_listing' | 'suspended';
@@ -102,6 +136,8 @@ export interface VersionChoiceInput<V extends PluginListingVersion = PluginListi
     requested?: string;
     advisories: readonly PluginAdvisory[];
     policy: ConsumptionPolicy;
+    /** Skip / refuse rescan-flagged versions (default: `PLUGIN_BLOCK_ON_NEW_CRITICAL`). */
+    blockFlagged?: boolean;
 }
 /**
  * Pick the listed version a reference resolves to (see the module doc), or
@@ -194,7 +230,7 @@ export declare function resolveListingReference(source: ListingDataSource, ref:
 export declare function listedVersionWarnings(input: {
     publisher: Pick<Publisher, 'handle' | 'tier'>;
     listing: Pick<PluginListing, 'name' | 'state'>;
-    version: Pick<PluginListingVersion, 'version' | 'deprecatedAt' | 'deprecationMessage' | 'specSnapshot'>;
+    version: Pick<PluginListingVersion, 'version' | 'deprecatedAt' | 'deprecationMessage' | 'specSnapshot'> & Partial<Pick<PluginListingVersion, 'scanFlaggedAt' | 'scanFlag'>>;
     advisories: readonly Pick<PluginAdvisory, 'severity' | 'state' | 'affectedRange' | 'fixedVersion' | 'summary'>[];
     policy: Pick<ConsumptionPolicy, 'secretsAllowedTiers'>;
 }): {