 (ns lambdacd.presentation.pipeline-state
+  "This namespace contains functions useful to convert the internal state of a pipeline into something more easy to use
+  for further processing, e.g. to present it to a user.
+
+  Functions taking a map step-id to step-result are usually called with the result of `lambdacd.state.core/get-step-results`"
   (:require [clj-time.core :as t]
             [clojure.tools.logging :as log]
             [clj-timeframes.core :as tf]

(defn- interval-duration [interval]
  (t/in-seconds interval))

(defn build-duration [step-ids-and-results]
  (->> step-ids-and-results
       (vals)
       (filter not-waiting?)

       (sort comp)
       (first)))

(defn earliest-first-update
  "Takes a map of step-ids to step results and finds the earliest timestamp for `:first-updated-at`, usually the start time of a pipeline"
  [step-ids-and-results]
  (->> (vals step-ids-and-results)
       (filter not-retriggered?)
       (first-with-key-ordered-by asc :first-updated-at)))

(defn latest-most-recent-update
  "Takes a map of step-ids to step results and finds the latest timestamp for `:most-recent-update-at`, usually the end or most recent update of a pipeline"
  [step-ids-and-results]
  (first-with-key-ordered-by desc :most-recent-update-at (vals step-ids-and-results)))

(defn build-that-was-retriggered
  "Takes a map of step-ids to step results and returns `nil` (for normal builds) or the build number of the build that was retriggered."
  [step-ids-and-results]
  (get-in step-ids-and-results [[1] :retrigger-mock-for-build-number]))

(defn- build-interval [step]
