walk the pipeline¶

%% Step-by-step presentation of one diagram, greyed out rather than hidden:
%% the whole pipeline is on screen from the first beat, and the parts the
%% story has not reached yet are faded back instead of removed. Asked for in
%% mermaid-js/mermaid#7710 (https://github.com/mermaid-js/mermaid/issues/7710):
%% advance on click or space, grey out what is still to come, and have a way
%% to highlight specific elements.
%% ---
%% Why fade instead of hide: the audience can see the shape of the whole
%% pipeline immediately and still knows exactly where you are. `dim` is the
%% action for that. Because a stateful action with no `dur` lasts exactly one
%% step, each step simply re-`dim`s whatever is still ahead of it — so the
%% grey set shrinks by one as you advance.
%% ---
%% `highlight` is the other half: it takes any list of ids, so it emphasises
%% one node, several nodes, or a whole subgraph in a single line. The last
%% step lights the entire green path at once with one `highlight release`.
%% ---
%% Nothing here is removed from the layout, so nothing ever moves, and
%% scrubbing backwards restores the exact grey/lit state of any earlier step.
%% ---
%% To present it: hit Present, then Space, → or a click on the diagram plays
%% exactly the next step and stops; ← goes back and 1–9 jump to a step.
flowchart TD
  push[Push to main]
  build[Build image]
  tests{Tests pass?}
  notify[Notify author]

  subgraph release[Release path]
    stage[Deploy to staging]
    smoke[Smoke checks]
    prod[Deploy to production]
  end

  push --> build
  build --> tests
  tests -->|no| notify
  tests -->|yes| stage
  stage --> smoke
  smoke --> prod

scenario "walk the pipeline" { speed: 1.0 }

  step commit "A commit lands on main" {
    desc: "Everything downstream is triggered by this one event, so it is the only lit box on screen. The rest of the pipeline is already drawn — greyed, not missing — which tells the audience how much is still to come."
    dim build, tests, notify, release, stage, smoke, prod
    highlight push { style: active }
  }

  step image "CI builds an image" {
    desc: "The build is the first thing that can fail, and it fails for boring reasons: a missing dependency, a compile error. Note that it happens once — the same artifact is what every later stage promotes."
    dim tests, notify, release, stage, smoke, prod
    flow push -> build { label: "webhook: sha 4f2c9a1", dur: 600ms }
    highlight build { style: active }
    gauge build { label: "artifact", value: "app:4f2c9a1" }
  }

  step verify "The test suite runs against that image" {
    desc: "This is the gate, and it is the only place the pipeline branches. Until it answers, both the notify box and the whole release path stay grey — the diagram is honestly showing that neither outcome has been chosen yet."
    dim notify, release, stage, smoke, prod
    flow build -> tests { label: "412 tests", dur: 700ms }
    highlight tests { style: active }
  }

  step verdict "Green, so the no-branch is retired" {
    desc: "The suite passes and the pipeline takes the yes edge. The notify box stays grey for the rest of the run: dimming the road not taken is more useful than deleting it, because the audience can still ask what would have happened."
    dim notify, smoke, prod
    flow tests -> stage { label: "yes · 0 failures", dur: 700ms }
    highlight stage { style: active }
    gauge tests { label: "result", value: "412 / 412" }
  }

  step probe "Staging gets a real request" {
    desc: "Smoke checks are not the test suite again — they hit the deployed service over the network, which is the first time configuration, secrets and DNS are exercised at all."
    dim notify, prod
    flow stage -> smoke { label: "GET /healthz + 3 journeys", dur: 700ms }
    highlight smoke { style: active }
  }

  step ship "Production takes the same artifact" {
    desc: "Nothing is rebuilt here; the image that passed the tests and the smoke checks is the image that ships. That is the property the whole pipeline exists to guarantee."
    dim notify
    flow smoke -> prod { label: "promote app:4f2c9a1", dur: 700ms }
    highlight prod { style: active }
    gauge prod { label: "live", value: "app:4f2c9a1" }
  }

  step whole "The green path, all at once" {
    desc: "One highlight naming a whole subgraph lights the three release stages together. Use it to close a walkthrough: the audience has seen the steps individually and now sees the shape they make."
    dim notify
    highlight release
    note release "one artifact, three gates" { side: right }
  }