@pipeline-builder/pipeline-data 4.1.24 → 4.1.25

package/lib/api/alert-destinations.d.ts

@@ -0,0 +1,17 @@
+/** One destination, reduced to what a delivery needs. */
+export interface NotificationDestination {
+    id: string;
+    /** `slack` | `webhook` | `email` | `in-app`. */
+    channel: string;
+    /** The URL or address. Bearer-equivalent for a webhook — never logged. */
+    target: string;
+    label: string;
+}
+/**
+ * Every ENABLED, undeleted destination for an org.
+ *
+ * Runs in the caller's ambient tenant context, so RLS is the tenancy gate — a caller
+ * without a context for this org reads nothing, which is the correct answer rather than
+ * an error.
+ */
+export declare function listEnabledAlertDestinations(orgId: string): Promise<NotificationDestination[]>;

package/lib/api/alert-destinations.js

@@ -0,0 +1,36 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Reading an org's notification destinations.
+ *
+ * These rows are ADMIN-OWNED: an org's admins decided where this organization's
+ * notifications go, and everything that needs to notify an org reads the same list
+ * rather than growing its own copy. Platform owns the writes (create, update, test,
+ * delete) in its alert-destination service; this is the read, here so that a service
+ * with no Drizzle dependency of its own can use it.
+ *
+ * Whoever reads this list must not treat it as a URL they chose. A caller that let a
+ * user name the target would have reinvented an SSRF, which is exactly why the write
+ * side validates the channel/target pairing and the transport resolves-and-pins the host.
+ */
+import { and, eq, isNull } from 'drizzle-orm';
+import { schema } from '../database/drizzle-schema.js';
+import { withTenantTx } from '../database/tenancy.js';
+/**
+ * Every ENABLED, undeleted destination for an org.
+ *
+ * Runs in the caller's ambient tenant context, so RLS is the tenancy gate — a caller
+ * without a context for this org reads nothing, which is the correct answer rather than
+ * an error.
+ */
+export async function listEnabledAlertDestinations(orgId) {
+    const rows = await withTenantTx((tx) => tx.select({
+        id: schema.orgAlertDestination.id,
+        channel: schema.orgAlertDestination.channel,
+        target: schema.orgAlertDestination.target,
+        label: schema.orgAlertDestination.label,
+    }).from(schema.orgAlertDestination)
+        .where(and(eq(schema.orgAlertDestination.orgId, orgId), eq(schema.orgAlertDestination.enabled, true), isNull(schema.orgAlertDestination.deletedAt))));
+    return rows;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWxlcnQtZGVzdGluYXRpb25zLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FwaS9hbGVydC1kZXN0aW5hdGlvbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsK0NBQStDO0FBQy9DLHNDQUFzQztBQUV0Qzs7Ozs7Ozs7Ozs7O0dBWUc7QUFFSCxPQUFPLEVBQUUsR0FBRyxFQUFFLEVBQUUsRUFBRSxNQUFNLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxFQUFFLE1BQU0sRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBQ3ZELE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQVl0RDs7Ozs7O0dBTUc7QUFDSCxNQUFNLENBQUMsS0FBSyxVQUFVLDRCQUE0QixDQUFDLEtBQWE7SUFDOUQsTUFBTSxJQUFJLEdBQUcsTUFBTSxZQUFZLENBQUMsQ0FBQyxFQUFFLEVBQUUsRUFBRSxDQUFDLEVBQUUsQ0FBQyxNQUFNLENBQUM7UUFDaEQsRUFBRSxFQUFFLE1BQU0sQ0FBQyxtQkFBbUIsQ0FBQyxFQUFFO1FBQ2pDLE9BQU8sRUFBRSxNQUFNLENBQUMsbUJBQW1CLENBQUMsT0FBTztRQUMzQyxNQUFNLEVBQUUsTUFBTSxDQUFDLG1CQUFtQixDQUFDLE1BQU07UUFDekMsS0FBSyxFQUFFLE1BQU0sQ0FBQyxtQkFBbUIsQ0FBQyxLQUFLO0tBQ3hDLENBQUMsQ0FBQyxJQUFJLENBQUMsTUFBTSxDQUFDLG1CQUFtQixDQUFDO1NBQ2hDLEtBQUssQ0FBQyxHQUFHLENBQ1IsRUFBRSxDQUFDLE1BQU0sQ0FBQyxtQkFBbUIsQ0FBQyxLQUFLLEVBQUUsS0FBSyxDQUFDLEVBQzNDLEVBQUUsQ0FBQyxNQUFNLENBQUMsbUJBQW1CLENBQUMsT0FBTyxFQUFFLElBQUksQ0FBQyxFQUM1QyxNQUFNLENBQUMsTUFBTSxDQUFDLG1CQUFtQixDQUFDLFNBQVMsQ0FBQyxDQUM3QyxDQUFDLENBQUMsQ0FBQztJQUNOLE9BQU8sSUFBaUMsQ0FBQztBQUMzQyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbi8qKlxuICogUmVhZGluZyBhbiBvcmcncyBub3RpZmljYXRpb24gZGVzdGluYXRpb25zLlxuICpcbiAqIFRoZXNlIHJvd3MgYXJlIEFETUlOLU9XTkVEOiBhbiBvcmcncyBhZG1pbnMgZGVjaWRlZCB3aGVyZSB0aGlzIG9yZ2FuaXphdGlvbidzXG4gKiBub3RpZmljYXRpb25zIGdvLCBhbmQgZXZlcnl0aGluZyB0aGF0IG5lZWRzIHRvIG5vdGlmeSBhbiBvcmcgcmVhZHMgdGhlIHNhbWUgbGlzdFxuICogcmF0aGVyIHRoYW4gZ3Jvd2luZyBpdHMgb3duIGNvcHkuIFBsYXRmb3JtIG93bnMgdGhlIHdyaXRlcyAoY3JlYXRlLCB1cGRhdGUsIHRlc3QsXG4gKiBkZWxldGUpIGluIGl0cyBhbGVydC1kZXN0aW5hdGlvbiBzZXJ2aWNlOyB0aGlzIGlzIHRoZSByZWFkLCBoZXJlIHNvIHRoYXQgYSBzZXJ2aWNlXG4gKiB3aXRoIG5vIERyaXp6bGUgZGVwZW5kZW5jeSBvZiBpdHMgb3duIGNhbiB1c2UgaXQuXG4gKlxuICogV2hvZXZlciByZWFkcyB0aGlzIGxpc3QgbXVzdCBub3QgdHJlYXQgaXQgYXMgYSBVUkwgdGhleSBjaG9zZS4gQSBjYWxsZXIgdGhhdCBsZXQgYVxuICogdXNlciBuYW1lIHRoZSB0YXJnZXQgd291bGQgaGF2ZSByZWludmVudGVkIGFuIFNTUkYsIHdoaWNoIGlzIGV4YWN0bHkgd2h5IHRoZSB3cml0ZVxuICogc2lkZSB2YWxpZGF0ZXMgdGhlIGNoYW5uZWwvdGFyZ2V0IHBhaXJpbmcgYW5kIHRoZSB0cmFuc3BvcnQgcmVzb2x2ZXMtYW5kLXBpbnMgdGhlIGhvc3QuXG4gKi9cblxuaW1wb3J0IHsgYW5kLCBlcSwgaXNOdWxsIH0gZnJvbSAnZHJpenpsZS1vcm0nO1xuaW1wb3J0IHsgc2NoZW1hIH0gZnJvbSAnLi4vZGF0YWJhc2UvZHJpenpsZS1zY2hlbWEuanMnO1xuaW1wb3J0IHsgd2l0aFRlbmFudFR4IH0gZnJvbSAnLi4vZGF0YWJhc2UvdGVuYW5jeS5qcyc7XG5cbi8qKiBPbmUgZGVzdGluYXRpb24sIHJlZHVjZWQgdG8gd2hhdCBhIGRlbGl2ZXJ5IG5lZWRzLiAqL1xuZXhwb3J0IGludGVyZmFjZSBOb3RpZmljYXRpb25EZXN0aW5hdGlvbiB7XG4gIGlkOiBzdHJpbmc7XG4gIC8qKiBgc2xhY2tgIHwgYHdlYmhvb2tgIHwgYGVtYWlsYCB8IGBpbi1hcHBgLiAqL1xuICBjaGFubmVsOiBzdHJpbmc7XG4gIC8qKiBUaGUgVVJMIG9yIGFkZHJlc3MuIEJlYXJlci1lcXVpdmFsZW50IGZvciBhIHdlYmhvb2sg4oCUIG5ldmVyIGxvZ2dlZC4gKi9cbiAgdGFyZ2V0OiBzdHJpbmc7XG4gIGxhYmVsOiBzdHJpbmc7XG59XG5cbi8qKlxuICogRXZlcnkgRU5BQkxFRCwgdW5kZWxldGVkIGRlc3RpbmF0aW9uIGZvciBhbiBvcmcuXG4gKlxuICogUnVucyBpbiB0aGUgY2FsbGVyJ3MgYW1iaWVudCB0ZW5hbnQgY29udGV4dCwgc28gUkxTIGlzIHRoZSB0ZW5hbmN5IGdhdGUg4oCUIGEgY2FsbGVyXG4gKiB3aXRob3V0IGEgY29udGV4dCBmb3IgdGhpcyBvcmcgcmVhZHMgbm90aGluZywgd2hpY2ggaXMgdGhlIGNvcnJlY3QgYW5zd2VyIHJhdGhlciB0aGFuXG4gKiBhbiBlcnJvci5cbiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGxpc3RFbmFibGVkQWxlcnREZXN0aW5hdGlvbnMob3JnSWQ6IHN0cmluZyk6IFByb21pc2U8Tm90aWZpY2F0aW9uRGVzdGluYXRpb25bXT4ge1xuICBjb25zdCByb3dzID0gYXdhaXQgd2l0aFRlbmFudFR4KCh0eCkgPT4gdHguc2VsZWN0KHtcbiAgICBpZDogc2NoZW1hLm9yZ0FsZXJ0RGVzdGluYXRpb24uaWQsXG4gICAgY2hhbm5lbDogc2NoZW1hLm9yZ0FsZXJ0RGVzdGluYXRpb24uY2hhbm5lbCxcbiAgICB0YXJnZXQ6IHNjaGVtYS5vcmdBbGVydERlc3RpbmF0aW9uLnRhcmdldCxcbiAgICBsYWJlbDogc2NoZW1hLm9yZ0FsZXJ0RGVzdGluYXRpb24ubGFiZWwsXG4gIH0pLmZyb20oc2NoZW1hLm9yZ0FsZXJ0RGVzdGluYXRpb24pXG4gICAgLndoZXJlKGFuZChcbiAgICAgIGVxKHNjaGVtYS5vcmdBbGVydERlc3RpbmF0aW9uLm9yZ0lkLCBvcmdJZCksXG4gICAgICBlcShzY2hlbWEub3JnQWxlcnREZXN0aW5hdGlvbi5lbmFibGVkLCB0cnVlKSxcbiAgICAgIGlzTnVsbChzY2hlbWEub3JnQWxlcnREZXN0aW5hdGlvbi5kZWxldGVkQXQpLFxuICAgICkpKTtcbiAgcmV0dXJuIHJvd3MgYXMgTm90aWZpY2F0aW9uRGVzdGluYXRpb25bXTtcbn1cbiJdfQ==

package/lib/api/reporting/analytics-queries.d.ts

@@ -0,0 +1,274 @@
+import type { FailureCategory } from '../../database/schema/reporting-analytics.js';
+/** The window and org scope every query takes. */
+export interface AnalyticsScope {
+    orgId: string;
+    /** `[self, ...descendants]` for a rollup; undefined = this org only. */
+    orgIds?: string[];
+    from: string;
+    to: string;
+}
+/** One pipeline's line in the breakdown. */
+export interface PipelineBreakdownRow {
+    pipelineId: string;
+    pipelineName: string | null;
+    project: string | null;
+    runs: number;
+    succeeded: number;
+    failed: number;
+    successPct: number | null;
+    p95Ms: number | null;
+    deploys: number;
+    /** The most recent failure's day and stage, for "what to look at first". */
+    lastFailureAt: string | null;
+    lastFailureStage: string | null;
+    buildSeconds: number;
+}
+/**
+ * Per-pipeline delivery, worst first.
+ *
+ * WORST FIRST, and capped, because the point of the section is "where should
+ * attention go". A list sorted by name, or an unbounded one, is a data dump: the
+ * lead still has to find the problem, which is the work the report was supposed to
+ * do. Ties break on volume, so a 50%-success pipeline that ran twice does not
+ * outrank one that ran two hundred times.
+ *
+ * `successPct` is NULL for a pipeline with no runs in the window — not 0. A
+ * pipeline nobody ran is not a pipeline that failed.
+ */
+export declare function getPipelineBreakdown(scope: AnalyticsScope, limit?: number): Promise<PipelineBreakdownRow[]>;
+/** One failure category's share of the period. */
+export interface FailureCategoryRow {
+    category: FailureCategory;
+    label: string;
+    count: number;
+    sharePct: number;
+    /** Whether the team can act on it, or it happened to them. */
+    teamActionable: boolean;
+    /** Change vs the previous period, in failures. */
+    change: number | null;
+    /** The pipelines it hit hardest. */
+    topPipelines: Array<{
+        pipelineId: string;
+        pipelineName: string | null;
+        count: number;
+    }>;
+}
+/**
+ * Failures by category, with the previous period's counts for the trend.
+ *
+ * SPLITS ACTIONABLE FROM NOT. A week whose failures were all cloud throttling is a
+ * different conversation from one whose failures were all broken tests, and
+ * presenting them in one ranked list invites exactly the wrong conclusion — a team
+ * being asked to fix an AWS capacity problem.
+ */
+export declare function getFailureAnalysis(scope: AnalyticsScope, previous?: {
+    from: string;
+    to: string;
+}): Promise<{
+    categories: FailureCategoryRow[];
+    total: number;
+    actionableTotal: number;
+}>;
+/** One stage's timing, for the drill-down. */
+export interface StagePerformanceRow {
+    stageName: string;
+    runs: number;
+    p50Ms: number | null;
+    p95Ms: number | null;
+    /** Change in p95 vs the previous period, as a percentage. */
+    p95ChangePct: number | null;
+    failed: number;
+}
+/**
+ * Per-stage timings for one pipeline, slowest first.
+ *
+ * The section a lead opens after the breakdown says a pipeline got slower: "which
+ * stage" is the next question, and answering it from raw events would mean a
+ * second scan of the same window.
+ */
+export declare function getStagePerformance(scope: AnalyticsScope, pipelineId: string, previous?: {
+    from: string;
+    to: string;
+}): Promise<StagePerformanceRow[]>;
+/** Build time by project and pipeline. No money anywhere. */
+export interface ResourceRow {
+    project: string | null;
+    pipelineId: string;
+    pipelineName: string | null;
+    buildSeconds: number;
+    runs: number;
+    sharePct: number;
+}
+/**
+ * Where the build time went.
+ *
+ * SECONDS, NOT DOLLARS. A cost figure needs the instance types, the spot/on-demand
+ * mix and the account's own discounts, none of which this platform knows — so a
+ * dollar number here would be a guess presented as an invoice. Build time is the
+ * thing actually measured.
+ */
+export declare function getResourceConsumption(scope: AnalyticsScope, limit?: number): Promise<{
+    pipelines: ResourceRow[];
+    totalBuildSeconds: number;
+}>;
+/** One commit's journey across environments. */
+export interface PromotionRow {
+    commitSha: string;
+    /** Environment → when it landed there, in the order it reached them. */
+    stops: Array<{
+        environment: string;
+        deployedAt: string;
+        hoursFromPrevious: number | null;
+    }>;
+    /** True when the commit reached a non-production environment and stopped. */
+    stuck: boolean;
+    furthest: string;
+}
+/**
+ * Where commits got to, and where they stopped.
+ *
+ * "Stuck" is the number worth reading. A commit that reached staging four days ago
+ * and never went further is work that is finished and not delivered — which does
+ * not appear in deployment frequency, success rate or lead time, because by every
+ * one of those measures nothing happened.
+ */
+export declare function getPromotionView(scope: AnalyticsScope, productionEnv?: string, limit?: number): Promise<{
+    commits: PromotionRow[];
+    stuckCount: number;
+}>;
+/** Outdated plugin usage, per pipeline and step. */
+export interface OutdatedPluginRow {
+    pipelineId: string;
+    pipelineName: string | null;
+    stageName: string;
+    stepName: string;
+    plugin: string;
+    inUse: string | null;
+    latest: string | null;
+    gap: string | null;
+    withinPolicy: boolean;
+}
+/**
+ * Which pipelines are behind on a plugin, worst gap first.
+ *
+ * Reads the DECLARED side (`pipeline_plugin_resolution`). A pipeline's declared
+ * range and what it last actually ran can disagree — which is why the vulnerability
+ * section below reads the deployed side and says which it is showing.
+ */
+export declare function getOutdatedPlugins(scope: AnalyticsScope, limit?: number): Promise<{
+    rows: OutdatedPluginRow[];
+    behindPipelines: number;
+    majorBehind: number;
+}>;
+/** A pipeline's exposure to a vulnerable plugin version. */
+export interface VulnerabilityRow {
+    pipelineId: string;
+    pipelineName: string | null;
+    plugin: string;
+    version: string;
+    /** `deployed` = what actually ran; `declared` = what the config asks for. */
+    source: string;
+    critical: number;
+    high: number;
+    findings: Array<Record<string, unknown>>;
+    flaggedAt: string;
+}
+/**
+ * Plugin vulnerabilities, per pipeline, Criticals first.
+ *
+ * SAYS WHETHER IT IS DECLARED OR DEPLOYED. A pipeline whose config was updated to a
+ * fixed version but which has not re-synthed is still running the vulnerable image,
+ * and a report that collapsed the two would tell a manager the problem is solved
+ * while the old image keeps running.
+ */
+export declare function getPluginVulnerabilities(scope: AnalyticsScope, limit?: number): Promise<{
+    rows: VulnerabilityRow[];
+    exposedPipelines: number;
+    criticalPipelines: number;
+}>;
+/** Adoption and deploy-tracking coverage within the reported scope. */
+export interface AdoptionSummary {
+    activePipelines: number;
+    totalPipelines: number;
+    /** Pipelines that produced a deploy row — i.e. ones DORA can see. */
+    deployTrackedPipelines: number;
+    /** By `creation_source`, for "are the golden paths being used". */
+    bySource: Record<string, number>;
+    /** Teams in the rollup that had activity. 1 for a single-org report. */
+    activeTeams: number;
+    /** Only when the org configured the assumption. Never platform-supplied. */
+    estimatedMinutesSaved: number | null;
+}
+/**
+ * Adoption, coverage and creation source.
+ *
+ * `deployTrackedPipelines` is the honest denominator for everything DORA says: a
+ * pipeline that has not re-synthed with deploy tags produces no deploy rows, so it
+ * is invisible to deployment frequency — and reporting "4 deploys" without saying
+ * that 20 of 30 pipelines cannot be seen is the single most misleading thing this
+ * feature could do.
+ */
+export declare function getAdoption(scope: AnalyticsScope, timeSavedMinutes?: number | null): Promise<AdoptionSummary>;
+/** One pipeline's failure streak and last successful day. */
+export interface PipelineStreakRow {
+    pipelineId: string;
+    /**
+     * Failures in the trailing run of days on which NOTHING succeeded.
+     *
+     * A LOWER BOUND, and deliberately so. The rollup is per day, so within the most
+     * recent day that did have a success there is no way to tell whether the failures
+     * came before or after it — that day is excluded rather than guessed at. What
+     * survives is a run of failures with no success anywhere between them, which is
+     * exactly the claim the finding makes.
+     */
+    consecutiveFailures: number;
+    /** The last day with at least one success, or null within the lookback. */
+    lastSuccessAt: Date | null;
+}
+/**
+ * Failure streaks and last-success dates, for the needs-attention rules.
+ *
+ * Reads the daily rollup, not `pipeline_events` — the same reason as everything
+ * else here: a streak that ended three weeks ago must still be readable after
+ * retention has swept the events that produced it.
+ *
+ * `lookbackDays` extends PAST the window on purpose. "Last succeeded 12 days ago"
+ * is the finding a weekly report most needs, and a query bounded by a 7-day window
+ * could never produce it.
+ */
+export declare function getPipelineStreaks(scope: AnalyticsScope, lookbackDays?: number): Promise<PipelineStreakRow[]>;
+/**
+ * Pipelines that RAN in the window but produced no deploy rows.
+ *
+ * A measurement gap, not a failure, and the reason a deployment-frequency number can
+ * be quietly wrong: a pipeline whose synth predates the `pb.deploys` tags deploys
+ * perfectly well and is invisible to every DORA aggregate. Nothing else in the
+ * report would say so.
+ */
+export declare function getUntrackedPipelines(scope: AnalyticsScope): Promise<string[]>;
+/**
+ * Pipelines running a plugin version with an OPEN Critical exposure.
+ *
+ * Point-in-time, not windowed: what matters is whether the pipeline is running one
+ * NOW. A Critical that was open last Tuesday and is fixed today is not something to
+ * put in front of a manager, and `fixed_at` is what says so.
+ *
+ * An ACCEPTED exposure is excluded. Someone with the authority to accept a risk has
+ * already decided about it in writing, with a reason and a deadline; re-raising it
+ * weekly is how a report teaches its reader to skip a section. The lapse of that
+ * acceptance is a separate finding (`lapsedAcceptances`).
+ */
+export declare function getVulnerablePipelines(scope: AnalyticsScope): Promise<string[]>;
+/**
+ * When each pipeline in the window was last changed.
+ *
+ * `pipelines.updated_at`, not an audit query: the audit trail lives in another store
+ * with its own retention, and the one fact this needs — "was this touched shortly
+ * before it broke" — is already on the row, durably, in the same transaction the
+ * change was made in.
+ *
+ * The consequence is stated rather than hidden: `updated_at` moves for ANY write,
+ * including a rename. So the finding says "after a configuration change", which is
+ * true of a rename too, and does not claim to name the change.
+ */
+export declare function getPipelineConfigChanges(scope: AnalyticsScope): Promise<Map<string, Date>>;