@pipeline-builder/pipeline-data 4.1.1 → 4.1.3

package/lib/api/reporting-service.d.ts

@@ -1,429 +1,6 @@
-interface ExecutionCount {
-    id: string;
-    project: string;
-    organization: string;
-    pipelineName: string | null;
-    total: number;
-    succeeded: number;
-    failed: number;
-    canceled: number;
-    firstExecution: string | null;
-    lastExecution: string | null;
-}
-interface TimeSeriesEntry {
-    period: string;
-    succeeded: number;
-    failed: number;
-    canceled: number;
-    successPct: number;
-}
-interface DurationStats {
-    id: string;
-    project: string;
-    pipelineName: string | null;
-    avgMs: number;
-    minMs: number;
-    maxMs: number;
-    p95Ms: number;
-    executions: number;
-}
-interface PipelineExecution {
-    executionId: string;
-    /** Rolled-up terminal status: succeeded | failed | canceled | in-progress. */
-    status: string;
-    startedAt: string | null;
-    endedAt: string | null;
-    durationMs: number | null;
-    /** First failing stage/action for the execution (null when it didn't fail). */
-    failingStage: string | null;
-    failingAction: string | null;
-}
-interface StageFailure {
-    stageName: string;
-    failures: number;
-    total: number;
-    failurePct: number;
-}
-interface StageBottleneck {
-    id: string;
-    pipelineName: string | null;
-    stageName: string;
-    avgMs: number;
-    maxMs: number;
-}
-interface ActionFailure {
-    actionName: string;
-    failures: number;
-    total: number;
-    failurePct: number;
-}
-interface ErrorEntry {
-    errorPattern: string;
-    occurrences: number;
-    affectedPipelines: number;
-    lastSeen: string;
-}
-interface PluginSummary {
-    total: number;
-    active: number;
-    inactive: number;
-    /** Counts per sharing rung — one bucket per `visibility` value. */
-    public: number;
-    org: number;
-    private: number;
-    uniqueNames: number;
-}
-interface TypeComputeDistribution {
-    pluginType: string;
-    computeType: string;
-    count: number;
-}
-interface VersionCount {
-    name: string;
-    versionCount: number;
-    latestVersion: string;
-    hasDefault: boolean;
-}
-interface BuildTimeSeriesEntry {
-    period: string;
-    succeeded: number;
-    failed: number;
-    successPct: number;
-}
-interface BuildDuration {
-    pluginName: string;
-    avgMs: number;
-    maxMs: number;
-    builds: number;
-}
-interface BuildFailure {
-    pluginName: string;
-    errorMessage: string;
-    occurrences: number;
-    lastSeen: string;
-}
-/** Effective standard-event retention (days): a valid per-org override wins,
- *  else the global env default. Shared by the sweep + the settings surface so
- *  they can't drift. The `-1` unlimited sentinel (Phase 8) passes straight
- *  through — the sweep reads it as "keep forever, skip this org's standard
- *  events". A positive override clamps to [1, RETENTION_MAX_DAYS]; a `null`, a
- *  non-integer, or any other out-of-range value (e.g. 0, -2) falls back to the
- *  env default. */
-export declare function resolveEventRetentionDays(override?: number | null): number;
-/** Effective DORA-source retention (days): a valid per-org override wins, else
- *  the global env default. The `-1` unlimited sentinel (Phase 8) passes straight
- *  through — the sweep reads it as "keep forever, skip this org's DORA-source
- *  windows". A positive override clamps to [1, RETENTION_MAX_DAYS]; a `null`, a
- *  non-integer, or any other out-of-range value (e.g. 0, -2) falls back to the
- *  env default. */
-export declare function resolveDoraRetentionDays(override?: number | null): number;
-/** The cutoff instant for a retention window: rows with `created_at` strictly
- *  before this (`< cutoff`) are expired. Deterministic for a fixed `now`. */
-export declare function retentionCutoff(now: Date, days: number): Date;
-/** Per-org retention override row (Phase 7). Both nullable ⇒ global defaults. */
-export interface ReportingRetentionSettings {
-    eventRetentionDays: number | null;
-    doraRetentionDays: number | null;
-    defaultEventRetentionDays: number;
-    defaultDoraRetentionDays: number;
-}
-/** Options for the reporting retention sweep. */
-export interface ReportingRetentionOptions {
-    /** Rows deleted per statement (default 1000). */
-    batchSize?: number;
-    /** Max batches per table per org per tick (default 50); the rest defers to
-     *  the next tick so a huge backlog can't hold locks too long. */
-    maxBatchesPerTable?: number;
-    /** Fixed "now" for the whole sweep (default `new Date()`). */
-    now?: Date;
-}
-/** Per-run purge tallies (also logged). */
-export interface ReportingRetentionCounts {
-    /** Orgs swept this run. */
-    orgs: number;
-    /** Standard `pipeline_events` (environment IS NULL) rows purged. */
-    standardEvents: number;
-    /** DORA-source `pipeline_events` (environment IS NOT NULL) rows purged. */
-    doraEvents: number;
-    /** `deployment_outcomes` rows purged. */
-    deploymentOutcomes: number;
-    /** `incidents` rows purged. */
-    incidents: number;
-}
-/**
- * DORA performance band. `null` = insufficient data to classify (no
- * deployments/failures/lead-time sample in the window), so the UI shows a
- * neutral state rather than mislabeling an empty window as "low".
- */
-export type DoraLevel = 'elite' | 'high' | 'medium' | 'low' | null;
-/** Optional scoping for {@link ReportingService.getDoraMetrics}. */
-export interface DoraOptions {
-    /** Restrict to a single pipeline (per-pipeline DORA). */
-    pipelineId?: string;
-    /** Restrict to a single deploy environment (else all deploy environments). */
-    environment?: string;
-    /**
-     * Per-org incident→deploy correlation window override (hours). When set (a
-     * positive finite number), the incident correlation uses it instead of the
-     * global `DORA_INCIDENT_WINDOW_HOURS`. The route resolves this from the org's
-     * `dora_settings` row (see {@link ReportingService.getIncidentSettings}) and
-     * passes it in; unset falls back to the env default.
-     */
-    incidentWindowHours?: number;
-}
-/**
- * Per-org reporting settings surfaced to the org-admin panel. `incidentWindowHours`
- * (Phase 5b) is the incident→deploy correlation window; `eventRetentionDays` /
- * `doraRetentionDays` (Phase 7) are the two retention-sweep windows. Each override
- * is `null` when unset (the paired `default*` field shows the env fallback applied).
- */
-export interface IncidentSettings {
-    /** The org's stored correlation-window override in hours, or `null` when unset. */
-    incidentWindowHours: number | null;
-    /** The global env default applied when no override is stored. */
-    defaultWindowHours: number;
-    /** Standard-event retention override in days, or `null` when unset (Phase 7). */
-    eventRetentionDays: number | null;
-    /** DORA-source retention override in days, or `null` when unset (Phase 7). */
-    doraRetentionDays: number | null;
-    /** Global standard-event retention default applied when unset (days). */
-    defaultEventRetentionDays: number;
-    /** Global DORA-source retention default applied when unset (days). */
-    defaultDoraRetentionDays: number;
-}
-/** A partial reporting-settings write (Phase 5b + 7). Only provided fields are
- *  upserted; omitted fields are left unchanged (an omitted retention field keeps
- *  its stored override / the global default). */
-export interface ReportingSettingsPatch {
-    incidentWindowHours?: number;
-    eventRetentionDays?: number;
-    doraRetentionDays?: number;
-}
-/** One row of the org-admin incidents list (recent incidents + deploy correlation). */
-export interface IncidentListItem {
-    incidentId: string;
-    environment: string;
-    severity: string;
-    openedAt: string | null;
-    resolvedAt: string | null;
-    createdAt: string | null;
-    /** True once the incident has a `resolved_at`. */
-    resolved: boolean;
-    /** The correlated deploy execution id (most recent successful deploy in-window), or null. */
-    correlatedExecutionId: string | null;
-    /** That deploy's completion instant, or null when uncorrelated. */
-    deployCompletedAt: string | null;
-}
-/** Result of the wiring-test dry-run correlation ({@link ReportingService.testIncidentCorrelation}). */
-export interface IncidentTestResult {
-    environment: string;
-    /** The synthetic incident's openedAt (now, ISO). */
-    openedAt: string;
-    /** The effective correlation window used. */
-    windowHours: number;
-    /** Whether a recent successful deploy to `environment` correlated. */
-    correlated: boolean;
-    /** The correlated deploy execution id, or null. */
-    executionId: string | null;
-    /** That deploy's completion instant, or null. */
-    deployCompletedAt: string | null;
-}
-/**
- * DORA metrics over a [from,to] window, org-scoped (single-org or rollup subtree).
- *
- * DEPLOY-BASIS — every metric derives from real DEPLOY-STAGE executions, i.e.
- * `pipeline_events` rows with `event_type='STAGE'` and a non-null `environment`
- * (the forwarder sets `environment` only for the stages a user declared in
- * `pb.deploys`). A CI-only build/test pipeline with no deploy stage produces NO
- * DORA data — there is no run-based fallback. The panel is empty until deployed
- * pipelines re-synth with the new deploy tags and start emitting deploy events.
- *
- * `production` is the headline environment; MTTR is measured production-only.
- */
-export interface DoraMetrics {
-    /** The [from,to] window echoed back (deploy `completed_at` range). */
-    window: {
-        from: string;
-        to: string;
-    };
-    /** The scoping applied (echoed for the UI); `null` when unscoped. */
-    filters: {
-        pipelineId: string | null;
-        environment: string | null;
-    };
-    /** The headline environment name (`production`). */
-    headline: string;
-    /** Per-environment DF / CFR / lead time. Sorted headline-first, then A→Z. */
-    environments: DoraEnvMetrics[];
-    /**
-     * Mean Time To Restore — PRODUCTION-ONLY, from `deployment_outcomes`.
-     * `median(restored.at − deployed.completed_at)` over restored production
-     * incidents (deltas clamped ≥0). `incidents` counts production deploys marked
-     * failed; `restored` counts those that recovered; `medianSeconds` is null when
-     * no restored incident has a resolvable deploy time.
-     */
-    meanTimeToRestore: {
-        incidents: number;
-        restored: number;
-        medianSeconds: number | null;
-        level: DoraLevel;
-    };
-    /**
-     * Coverage reconciliation — registered pipelines with no observed deploy in
-     * the window. A high `withoutDeploys` count means DORA is blind to most of the
-     * fleet (pipelines that haven't re-synthed with deploy tags, or don't deploy).
-     */
-    coverage: {
-        /** Pipelines in the registry (org-scoped). */
-        registered: number;
-        /** Registered pipelines with ≥1 deploy-stage execution in the window. */
-        deploying: number;
-        /** registered − deploying (clamped ≥0). */
-        withoutDeploys: number;
-    };
-}
-/** Per-environment DORA metrics (deployment frequency, CFR, lead time). */
-export interface DoraEnvMetrics {
-    environment: string;
-    /** Deployment Frequency — successful deploy-stage executions for this env. */
-    deploymentFrequency: {
-        deployments: number;
-        perDay: number;
-        level: DoraLevel;
-    };
-    /**
-     * Change Failure Rate — two-class:
-     * `(deployTimeFailures + postDeployFailures) / attempts`.
-     * - `deployTimeFailures` — deploy stage `result=failed` (from events).
-     * - `postDeployFailures` — a successful deploy later marked failed in prod
-     *   (from `deployment_outcomes`).
-     * - `attempts` — all terminal deploy-stage attempts (succeeded + failed).
-     */
-    changeFailureRate: {
-        rate: number;
-        deployTimeFailures: number;
-        postDeployFailures: number;
-        attempts: number;
-        level: DoraLevel;
-    };
-    /**
-     * Lead Time — MEASURED: `median(deploy_completed − oldest_commit_time)` over
-     * successful deploys with a resolvable commit timestamp (deltas clamped ≥0).
-     * `medianSeconds` is `null` (= unknown) when no successful deploy in this env
-     * carried a `commit_timestamp`. The old median-run-duration proxy is removed.
-     */
-    leadTime: {
-        /** Successful deploys with a resolvable commit time (the median sample). */
-        deployments: number;
-        medianSeconds: number | null;
-        level: DoraLevel;
-    };
-}
-/** One interval bucket of the DORA trend (deploy frequency + change failure). */
-export interface DoraTrendPoint {
-    /** Bucket start (DATE_TRUNC of the deploy `completed_at`), ISO text. */
-    period: string;
-    /** Successful deploy-stage executions in the bucket. */
-    deployments: number;
-    /** Failed deploy-stage executions in the bucket. */
-    failed: number;
-    /** succeeded + failed in the bucket (deploy attempts). */
-    total: number;
-    /** failed/total as a percent (0 when total is 0). Deploy-time CFR only. */
-    changeFailurePct: number;
-}
-/** Per-stage build-health metrics (Phase 6) for one pipeline over a window. */
-export interface BuildHealthStage {
-    stage: string;
-    /** Terminal stage runs (succeeded + failed) in the window. */
-    runs: number;
-    successes: number;
-    failures: number;
-    /** successes / runs as a percent (0 when runs is 0). */
-    successRate: number;
-    /** Duration percentiles over the stage's terminal runs; null when no durations. */
-    p50Ms: number | null;
-    p90Ms: number | null;
-    p99Ms: number | null;
-}
-/**
- * Per-pipeline build-health breakdown (Phase 6). Standard reporting (NOT
- * `advanced_reporting`-gated) — per-stage success rate + timing percentiles, with
- * totals summed across stages.
- */
-export interface BuildHealth {
-    stages: BuildHealthStage[];
-    totals: {
-        runs: number;
-        failures: number;
-        failureRate: number;
-    };
-}
-/** Post-deploy incident marker (Phase 5) accepted by `ReportingService.recordIncident`. */
-export interface IncidentInput {
-    incidentId: string;
-    environment: string;
-    openedAt: string;
-    resolvedAt?: string;
-    severity: string;
-}
-/** Event payload accepted by `ReportingService.ingestEvents`. Mirrors the route's Zod shape. */
-export interface IngestEvent {
-    /** Stable pipeline id the events Lambda read from the `pb.pipeline-id`
-     *  tag (= the platform pipelineId). The registry join key. */
-    pipelineId: string;
-    eventSource: 'codepipeline' | 'codebuild' | 'plugin-build';
-    eventType: 'PIPELINE' | 'STAGE' | 'ACTION' | 'BUILD';
-    status: string;
-    executionId?: string;
-    stageName?: string;
-    actionName?: string;
-    /** Human-readable failure reason (Action events). */
-    errorMessage?: string;
-    startedAt?: string;
-    completedAt?: string;
-    durationMs?: number;
-    /** Source commit id of the change being shipped (DORA deploy attribution). */
-    commitSha?: string;
-    /** Source ref/branch (DORA deploy attribution). */
-    commitRef?: string;
-    /** Deploy target (e.g. "production"). Its presence on a STAGE/ACTION event
-     *  marks a real deployment (derived server-side — there is no `isDeploy`). */
-    environment?: string;
-    /** Oldest unshipped commit timestamp (ISO 8601) for measured lead time. */
-    commitTimestamp?: string;
-    /** Number of commits shipped in this change (≥1). */
-    commitCount?: number;
-    detail?: Record<string, unknown>;
-}
-/**
- * Per-event metric descriptor emitted (via the {@link ReportingService.ingestEvents}
- * `onMetric` hook) for each REGISTERED terminal deploy/stage event, so the route
- * layer can fan them into Prometheus counters without pipeline-data importing
- * api-server's metrics registry. `result` is the terminal outcome; `environment`
- * is non-null only for a deploy-stage event.
- */
-export interface IngestMetric {
-    pipelineId: string;
-    orgId: string;
-    stage: string;
-    environment: string | null;
-    result: 'succeeded' | 'failed';
-}
-/** Counts + the (possibly truncated) list of unregistered pipeline ids the caller can log. */
-export interface IngestResult {
-    inserted: number;
-    skipped: number;
-    unregisteredPipelineIds: string[];
-}
-/**
- * Read-only reporting service for pipeline execution and plugin inventory aggregations.
- * Does not extend CrudService — reports are aggregate queries, not entity CRUD.
- *
- * All queries are cached in-memory to avoid repeated expensive SQL aggregations:
- * - Inventory queries (plugin summary/distribution/versions): 5 min TTL
- * - Timeseries queries (execution/build metrics with date ranges): 2 min TTL
- */
+import type { ExecutionCount, TimeSeriesEntry, DurationStats, PipelineExecution, StageFailure, StageBottleneck, ActionFailure, ErrorEntry, PluginSummary, TypeComputeDistribution, VersionCount, BuildTimeSeriesEntry, BuildDuration, BuildFailure, ReportingRetentionOptions, ReportingRetentionCounts, DoraOptions, IncidentSettings, ReportingSettingsPatch, IncidentListItem, IncidentTestResult, DoraMetrics, DoraTrendPoint, BuildHealth, IncidentInput, IngestEvent, IngestMetric, IngestResult } from './reporting/types.js';
+export type { BuildHealth, BuildHealthStage, DoraEnvMetrics, DoraLevel, DoraMetrics, DoraOptions, DoraTrendPoint, IncidentInput, IncidentListItem, IncidentSettings, IncidentTestResult, IngestEvent, IngestMetric, IngestResult, ReportingRetentionCounts, ReportingRetentionOptions, ReportingRetentionSettings, ReportingSettingsPatch, } from './reporting/types.js';
+export { resolveDoraRetentionDays, resolveEventRetentionDays, retentionCutoff } from './reporting/retention.js';
 export declare class ReportingService {
     #private;
     /** Invalidate all cached reports for an org (call after event ingest). */
@@ -438,23 +15,6 @@ export declare class ReportingService {
      * Returns counts + a sample of unregistered pipeline ids for observability.
      */
     ingestEvents(events: IngestEvent[], onMetric?: (m: IngestMetric) => void): Promise<IngestResult>;
-    /**
-     * Build the org-scope predicate for a report query. With `orgIds` (the
-     * org → team rollup — a parent's `[self, ...descendants]`) it becomes an
-     * `IN (...)` over the subtree; otherwise the single-org `= $org`. Returns a
-     * `multi` flag so callers can run multi-org reads under sysadmin context
-     * (the subtree spans orgs outside the request's RLS scope) and salt the
-     * cache key.
-     */
-    private orgScope;
-    /**
-     * Run a report read. Single-org reads use the per-org cache (invalidated on
-     * that org's event ingest). Rollup (multi-org) reads **bypass the cache** and
-     * run under sysadmin context: they're admin-only and lower-frequency, and a
-     * child org's event ingest can't invalidate a parent's rollup entry (reporting
-     * has no org tree), so caching them would serve stale aggregates. Always fresh.
-     */
-    private runReport;
     /** 1.1 Execution count per pipeline with status breakdown. */
     getExecutionCount(orgId: string, orgIds?: string[], range?: {
         from?: string;
@@ -504,66 +64,14 @@ export declare class ReportingService {
      */
     getErrors(orgId: string, from: string, to: string, limit?: number, orgIds?: string[]): Promise<ErrorEntry[]>;
     /**
-     * 1.9 DORA metrics over a [from,to] deploy-completion window, org-scoped +
-     * rollup-aware. DEPLOY-BASIS ONLY — every metric derives from real deploy-stage
-     * executions (`event_type='STAGE'` with a non-null `environment`, set by the
-     * forwarder for the stages a user declared in `pb.deploys`). No run-based
-     * fallback: a pipeline with no deploy stage produces no DORA data.
-     *
-     * Four scoped SQL scans run inside one tx (each org-gated by `p.org_id ${pred}`
-     * / `o.org_id ${pred}` so a rollup passes the org→team subtree and a foreign
-     * org's rows never enter): (1) terminal deploy rows PER (execution, env) — one
-     * "deployment" = one execution reaching an env (D1) — → DF / deploy-time CFR /
-     * measured lead time (lead time joins the execution's earliest commit, D2);
-     * the scan also reaches back `windowHours` before `from` so incidents opened
-     * near the window start can correlate to a just-prior deploy; (2) `deployment_outcomes`
-     * in-window → post-deploy CFR component; (3) production restored/failed
-     * outcomes joined to their deploy → MTTR; (4) registry vs deploying → coverage.
-     * The cross-source medians (lead time, MTTR) are computed in JS from clamped
-     * (≥0) deltas.
-     *
-     * @param opts.pipelineId    restrict to one pipeline (per-pipeline DORA)
-     * @param opts.environment   restrict to one deploy environment
+     * The four DORA measures plus their per-environment breakdown.
+     * Implementation in ./reporting/dora.ts — see that file's header for why.
      */
     getDoraMetrics(orgId: string, from: string, to: string, orgIds?: string[], opts?: DoraOptions): Promise<DoraMetrics>;
-    /**
-     * Shape the raw DORA scan rows into the public {@link DoraMetrics}. Buckets the
-     * terminal deploy rows by environment (DF / deploy-time CFR / measured lead),
-     * folds in the post-deploy failure counts (manual outcomes + webhook-ingested
-     * incidents, deduped by deploy execution), computes production MTTR from both
-     * sources (incident `resolved_at − opened_at` taking precedence over the manual
-     * `restored − deployed`), and reconciles coverage — all cross-source medians
-     * over deltas clamped ≥0.
-     *
-     * Phase 5 incident correlation: each incident is attributed to the most recent
-     * SUCCESSFUL deploy to its environment with `completed_at ≤ opened_at` within
-     * {@link DORA_INCIDENT_WINDOW_HOURS}. That deploy is a post-deploy failure; an
-     * uncorrelated incident (no eligible deploy) contributes nothing.
-     */
-    private shapeDora;
-    /**
-     * 1.9b DORA trend — deployment frequency + deploy-time change-failure rate
-     * bucketed by `interval` (day/week/month) for a sparkline. Deploy-basis like
-     * getDoraMetrics: buckets terminal deploy-stage executions on their
-     * `completed_at`. Shares the org/rollup + pipelineId/environment scoping. MTTR,
-     * lead time, and post-deploy CFR are intentionally omitted (too heavy to bucket).
-     */
+    /** DORA measures bucketed over time. */
     getDoraTrend(orgId: string, interval: string, from: string, to: string, orgIds?: string[], opts?: DoraOptions): Promise<DoraTrendPoint[]>;
-    /**
-     * 1.10 Per-pipeline BUILD HEALTH (Phase 6) — a standard (NOT `advanced_reporting`)
-     * per-stage breakdown for one pipeline over a [from,to] window. Aggregates the
-     * existing `pipeline_events` STAGE rows: each stage is rolled up per execution
-     * to a terminal status (FAILED wins, then SUCCEEDED) + its max duration, then
-     * grouped per stage into run/success/failure counts, a success rate, and
-     * duration percentiles (p50/p90/p99). Totals sum across stages. Org-scoped via
-     * the pipeline join (`p.org_id ${pred}`) + rollup-aware like the sibling reports;
-     * a pipelineId owned by another org returns an empty breakdown.
-     */
+    /** Per-pipeline build health (stage pass rates over a window). */
     getBuildHealth(orgId: string, pipelineId: string, from: string, to: string, orgIds?: string[]): Promise<BuildHealth>;
-    /** 2.1 Plugin summary — counts and breakdowns.
-     *  INTENTIONALLY SINGLE-ORG (no rollup): plugin inventory is an org-owned
-     *  asset count, not an execution/build activity report, so a parent's view is
-     *  its own plugins — teams manage their own inventory. Single `= $org` scope. */
     getPluginSummary(orgId: string): Promise<PluginSummary>;
     /** 2.2 Type & compute distribution.
      *  INTENTIONALLY SINGLE-ORG (no rollup): plugin inventory is per-org (see
@@ -682,4 +190,3 @@ export declare class ReportingService {
     purgeExpiredReportingData(opts?: ReportingRetentionOptions): Promise<ReportingRetentionCounts>;
 }
 export declare const reportingService: ReportingService;
-export {};