@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/reporting/check-run-summary.d.ts

@@ -1,13 +1,10 @@
 /**
- * Check run summary, annotation, and progress text builders.
+ * Pure builders for GitHub Checks API summaries, annotations and progress text, from step
+ * results and log buffers. No side effects, no API calls.
  *
- * These are pure functions that produce markdown and annotation objects
- * for the GitHub Checks API. No side effects, no API calls -- just data
- * transformation from step results + log buffers to GitHub-ready output.
- *
- * Per locked decisions:
+ * Output contract:
  * - Summary headline: "Job '{jobName}' failed (N/M steps passed)" or success equivalent
- * - Step table with Status | Step | Duration columns
+ * - Step table with Step | Status | Duration columns
  * - Failed steps: error + last 20 log lines in code blocks
  * - Annotations: failure/warning level, capped at 50
  * - Progress: checklist-style with emoji prefixes
@@ -56,17 +53,13 @@ interface BuildCheckRunSummaryOptions {
         requestId: string;
         runId: string;
     };
-    /** Total job duration in milliseconds. */
+    /** Milliseconds. */
     jobDurationMs?: number;
     /**
-     * Bytes a caller will add around the returned summary — the reduced-privilege
-     * note it prepends, the annotation-count line it appends — subtracted from
-     * the byte budget below.
-     *
-     * Without it the budget is spent in full here and the caller's own bytes push
-     * the final string over the API's cap, which rejects the entire update and
-     * leaves the check run unresolved. Reserving instead drops one more tier of
-     * log lines, which costs context rather than the whole report.
+     * Bytes the caller adds around the summary (the prepended reduced-privilege note, the
+     * appended annotation-count line), subtracted from the byte budget. Without it the caller's
+     * bytes push the string over the API cap, which rejects the whole update and leaves the
+     * check run unresolved; reserving drops one more log tier instead.
      */
     reservedBytes?: number;
 }
@@ -85,38 +78,26 @@ interface BuildProgressTextOptions {
 /** GitHub Checks API output.summary byte limit. */
 export declare const SUMMARY_BYTE_LIMIT = 65535;
 /**
- * Cut `summary` so it fits the API's cap, whatever a caller wrapped around it.
- *
- * The last line of defence, not the primary mechanism: `reservedBytes` is what
- * keeps a summary readable by dropping log tiers, and this only runs when the
- * final string is still over. Truncating at a UTF-8 boundary matters — a cut
- * through a multi-byte sequence produces a replacement character and can leave
- * the string one byte over the cap it was cut to fit.
+ * Cut `summary` to fit the API's cap, whatever a caller wrapped around it. The last line of
+ * defence: `reservedBytes` keeps a summary readable by dropping log tiers first.
  */
 export declare function clampSummaryToLimit(summary: string, limit?: number): string;
 export { formatDuration } from '@kici-dev/shared';
 /**
- * Build a rich markdown summary for a GitHub Check run output.summary field.
- *
- * Includes: headline, step table, failure details with log context, trace footer.
- * Respects the 65535 byte limit with progressive log truncation, minus whatever
- * `reservedBytes` the caller will wrap around the result.
+ * Markdown for a check run's output.summary: headline, step table, failure details with log
+ * context, trace footer. Fits 65535 bytes minus `reservedBytes` by progressive log truncation.
  */
 export declare function buildCheckRunSummary(opts: BuildCheckRunSummaryOptions): string;
 /**
- * Build GitHub Check annotation objects from step results and source locations.
- *
- * Returns an object with the annotations array (capped at 50) and the count
- * of remaining annotations that could not be included.
+ * Annotations for failed steps with a source location, capped at 50; `remainingCount` is how
+ * many did not fit.
  */
 export declare function buildAnnotations(opts: BuildAnnotationsOptions): {
     annotations: CheckAnnotation[];
     remainingCount: number;
 };
 /**
- * Build a checklist-style markdown string for live check run updates.
- *
- * Example:
+ * Checklist-style markdown for live check run updates, for example:
  *   checkmark Install deps (1.2s)
  *   checkmark Build (3.4s)
  *   hourglass Run tests...

package/dist/reporting/check-run-tracking-store.d.ts

@@ -2,11 +2,8 @@ import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { StepProgressEntry } from './check-run-summary.js';
 /**
- * Composite key identifying a single check-run row.
- *
- * Matches the table primary key `(provider, owner, repo, sha, check_name)`.
- * Used by the L1 in-memory cache and as the parameter shape for every
- * store method.
+ * Matches the table primary key `(provider, owner, repo, sha, check_name)`. Also the
+ * L1 in-memory cache key.
  */
 export interface CheckRunTrackingKey {
     provider: string;
@@ -15,40 +12,31 @@ export interface CheckRunTrackingKey {
     sha: string;
     checkName: string;
 }
-/**
- * Snapshot of all per-key check-run state. Mirrors the columns of the
- * `check_run_tracking` table with the in-memory shapes the consumer
- * already uses.
- */
+/** Mirrors the `check_run_tracking` columns, in the in-memory shapes the consumer uses. */
 export interface CheckRunTrackingState {
     /** GitHub Checks API check-run ID. Undefined when not yet created. */
     checkRunId?: number;
-    /** Build check-run lifecycle marker. */
     buildCreationState?: 'pending' | 'completed';
     /** Live step-progress entries shown in the check run's `output.summary`. */
     stepProgress: StepProgressEntry[];
-    /** Timestamp the first running-step transition was sent to GitHub. */
+    /** When the first running-step transition was sent to GitHub. */
     inProgressSentAt?: Date;
     /**
-     * Timestamp the terminal (`completed`) update was accepted by the provider.
-     * Undefined means we have no record of sending it — not proof it failed.
+     * When the provider accepted the terminal (`completed`) update.
+     * Undefined means no record of sending it — not proof it failed.
      */
     terminalSentAt?: Date;
     /**
-     * KiCI run this check-run belongs to. Written at create time so the row
-     * records its owning run; it is an attribution/lookup key, not a retention
-     * key — the sweep prunes on `updated_at` age alone.
+     * Owning KiCI run, written at create time. An attribution/lookup key, not a
+     * retention key — the sweep prunes on `updated_at` age alone.
      */
     runId?: string;
     /** Last persisted update time; powers debounce-after-failover recovery. */
     updatedAt?: Date;
 }
 /**
- * DB persistence for `CheckRunReporter` check-run state.
- *
- * Backed by the `check_run_tracking` table — one row per
- * `(provider, owner, repo, sha, check_name)`. Replaces six in-memory
- * `Map`s previously held inside `CheckRunReporter`:
+ * DB persistence for `CheckRunReporter` check-run state, one `check_run_tracking` row per
+ * `(provider, owner, repo, sha, check_name)`. The reporter's in-memory maps persist as:
  *
  *   - `checkRunIds`            → `check_run_id` column
  *   - `pendingBuildCreations`  → `build_creation_state` column
@@ -56,133 +44,92 @@ export interface CheckRunTrackingState {
  *   - `inProgressSent`         → `in_progress_sent_at` column
  *   - `runIdToKeys`            → indexed `run_id` column + `listKeysByRunId`
  *
- * The `progressTimers` Map is intentionally NOT persisted — debounce
- * timers are reconstructed on demand. After a coord failover the very
- * next `updateStepProgress` either flushes immediately (debounce window
- * elapsed) or starts a fresh timer.
+ * `progressTimers` is intentionally NOT persisted: after a coord failover the next
+ * `updateStepProgress` either flushes immediately (debounce window elapsed) or starts a
+ * fresh timer.
  *
- * The consumer keeps an L1 in-memory cache in front of this store; the
- * store itself is stateless beyond the connection it holds.
+ * The consumer keeps an L1 in-memory cache in front; the store is stateless beyond its
+ * connection.
  */
 export declare class CheckRunTrackingStore {
     private readonly db;
     constructor(db: Kysely<Database>);
     /**
-     * Atomically set / overwrite the check-run ID for a key.
-     *
-     * Performed as an upsert so a re-issued setPending after a coord
-     * failover replaces the prior ID rather than silently leaving a row
-     * mismatched with the GitHub-side state.
+     * Upsert, so a re-issued setPending after a coord failover replaces the prior ID rather
+     * than leaving the row mismatched with the GitHub-side state.
      *
-     * `runId` is written alongside so the row records which run owns it from
-     * the moment it is created. A row created without it carries a NULL
-     * `run_id`, which makes `listKeysByRunId` under-report and leaves the
-     * column useless to an operator asking which run posted a given check.
+     * Pass `runId`: a row created without it carries a NULL `run_id`, which makes
+     * `listKeysByRunId` under-report and hides which run posted a given check.
      */
     setCheckRunId(key: CheckRunTrackingKey, checkRunId: number, runId?: string): Promise<void>;
     /**
-     * Lookup the check-run ID for a key. Returns undefined if no row exists
-     * yet OR the row exists but the GitHub create has not finished
-     * persisting an ID (the build-creation in-flight window).
+     * Undefined if no row exists yet OR the GitHub create has not persisted an ID yet
+     * (the build-creation in-flight window).
      */
     getCheckRunId(key: CheckRunTrackingKey): Promise<number | undefined>;
     /**
-     * Mark a build check-run as having an in-flight create. Returns true if
-     * this caller won the race (no prior row, or row had no in-flight state).
-     * Used to prevent a replacement coord from re-issuing a `checks.create()`
-     * against the same SHA when the original create is still pending.
+     * Mark a build check-run as having an in-flight create (a plain upsert; it
+     * does not report whether this caller won a race). Used to prevent a
+     * replacement coord from re-issuing a `checks.create()` against the same SHA
+     * when the original create is still pending.
      */
     markBuildCreationPending(key: CheckRunTrackingKey, runId?: string): Promise<void>;
-    /**
-     * Mark a build check-run create as complete. Idempotent.
-     */
+    /** Idempotent. */
     markBuildCreationComplete(key: CheckRunTrackingKey): Promise<void>;
-    /**
-     * Replace the step-progress array for a key.
-     */
     setStepProgress(key: CheckRunTrackingKey, steps: StepProgressEntry[], runId?: string): Promise<void>;
-    /**
-     * Mark the first in-progress transition as sent. Used to keep the
-     * single "did we already kick this check run into in_progress?" guard
-     * cluster-wide.
-     */
+    /** Keeps the "already kicked this check run into in_progress?" guard cluster-wide. */
     markInProgressSent(key: CheckRunTrackingKey, runId?: string): Promise<void>;
     /**
-     * Stamp that the terminal (`completed`) provider update was sent.
-     *
-     * Mirrors `markInProgressSent`. Best-effort like every write on this table —
-     * the caller swallows failures, because a tracking write must never break
-     * check-run reporting — so a null column is "no record", not "never sent".
+     * Mirrors `markInProgressSent`. Best-effort like every write on this table — the caller
+     * swallows failures, because a tracking write must never break check-run reporting — so
+     * a null column is "no record", not "never sent".
      */
     markTerminalSent(key: CheckRunTrackingKey, runId?: string): Promise<void>;
-    /**
-     * Get the full state snapshot for a key. Used by the L1 cache to
-     * hydrate on miss and by tests to verify the on-disk layout. Returns
-     * undefined when no row exists.
-     */
+    /** Hydrates the L1 cache on miss; tests use it to verify the on-disk layout. */
     getState(key: CheckRunTrackingKey): Promise<CheckRunTrackingState | undefined>;
-    /**
-     * Delete a single row. Returns true if the row existed.
-     */
+    /** Returns true if the row existed. */
     deleteRow(key: CheckRunTrackingKey): Promise<boolean>;
     /**
-     * List every key currently tracked for a runId — the runId → keys reverse
-     * index that `CheckRunReporter` otherwise holds only in memory, so a
+     * The runId → keys reverse index `CheckRunReporter` otherwise holds only in memory, so a
      * replacement coord that never saw the run can still recover it. Index
      * `idx_check_run_tracking_run_id` keeps this O(matches).
      *
-     * No caller in tree: run-prune stopped consulting the store once row
-     * lifetime moved to {@link pruneStale}. Kept as the read half of the
-     * `run_id` column, beside {@link deleteByRunId}.
+     * No caller in tree: row lifetime is {@link pruneStale}'s job. Kept as the read half of
+     * the `run_id` column, beside {@link deleteByRunId}.
      */
     listKeysByRunId(runId: string): Promise<CheckRunTrackingKey[]>;
     /**
-     * Delete every row for a runId.
-     *
-     * Not on the run-prune path: `cleanupRun` evicts only its in-memory state,
-     * because a row deleted at prune time strands a late terminal PATCH that
-     * still has to resolve its check-run ID. Routine reclamation is
-     * {@link pruneStale}. This remains as the targeted escape hatch for
-     * discarding one run's rows deliberately.
+     * Targeted escape hatch for deliberately discarding one run's rows; routine reclamation
+     * is {@link pruneStale}. Not on the run-prune path: `cleanupRun` evicts only in-memory
+     * state, because a row deleted at prune time strands a late terminal PATCH that still
+     * has to resolve its check-run ID.
      */
     deleteByRunId(runId: string): Promise<number>;
     /**
-     * Delete every row untouched for longer than `retentionDays`, and return
-     * how many were removed. `retentionDays <= 0` disables the sweep, matching
-     * the `JobQueue.pruneTerminalDispatchRows` convention.
+     * Delete rows untouched for longer than `retentionDays`; returns the count.
+     * `retentionDays <= 0` disables the sweep (the `JobQueue.pruneTerminalDispatchRows`
+     * convention). Called from the hourly cleanup tick.
      *
-     * `updated_at` is the staleness signal because the table carries no status
-     * column, and the rows that most need reaping are precisely the ones with no
-     * `run_id` to join on — so the predicate is age alone, deliberately
-     * unfiltered by `run_id`. Every upsert bumps `updated_at`, so a run that is
-     * still emitting check-run traffic keeps its rows fresh; a workflow-level
-     * row, written once at create, ages from creation.
+     * The predicate is `updated_at` age alone, deliberately unfiltered by `run_id`: the
+     * table has no status column, and the rows that most need reaping have no `run_id` to
+     * join on. Every upsert bumps `updated_at`, so a run still emitting check-run traffic
+     * keeps its rows fresh; a workflow-level row, written once at create, ages from creation.
      *
-     * Inactivity age rather than run completion is what keeps a reader safe: a
-     * row a diagnostic is polling for cannot disappear underneath it, because
-     * the window is days and the row is only removed once nothing has touched
-     * it for that long.
+     * Inactivity age rather than run completion keeps a reader safe: a row a diagnostic is
+     * polling cannot vanish underneath it, because the window is days.
      *
-     * The bound this trades for that safety: age is measured on check-run
-     * writes, not on run liveness, so a run that stays live while emitting no
-     * check-run traffic for longer than the window — a run parked on a manual
-     * approval gate, whose hold statuses go through `CheckStatusPoster` and
-     * never touch this table — has its rows swept while it is still running.
-     * The reporter's L1 cache still holds the ID, so its terminal update lands
-     * anyway on a coord that stayed up; it takes a restart or failover across
-     * that window to leave the update with no row to load through and no
+     * The trade-off: a run that stays live with no check-run traffic for longer than the
+     * window — e.g. parked on a manual approval gate, whose hold statuses go through
+     * `CheckStatusPoster` and never touch this table — has its rows swept while running. The
+     * reporter's L1 cache still holds the ID, so the terminal update lands on a coord that
+     * stayed up; only a restart or failover across that window leaves it with no row and no
      * check-run ID to resolve.
-     *
-     * Called from the hourly cleanup tick.
      */
     pruneStale(retentionDays: number): Promise<number>;
     private selectRow;
     private upsertRow;
 }
-/**
- * Convert a raw DB row to the in-memory `CheckRunTrackingState` shape.
- * Exported for direct use from tests that bypass the store.
- */
+/** Exported for tests that bypass the store. */
 export declare function rowToState(row: {
     check_run_id: number | string | null;
     build_creation_state: string | null;