diff --git a/changelog.d/added-workflowmodel-versions-diff-confirm.md b/changelog.d/added-workflowmodel-versions-diff-confirm.md new file mode 100644 index 0000000000..c1b23e4869 --- /dev/null +++ b/changelog.d/added-workflowmodel-versions-diff-confirm.md @@ -0,0 +1 @@ +- Workflow models (RFC phase 4, backend): `GET /api/workflows/{name}/versions`, a deterministic structural diff between two versions (`GET …/{name}/diff?from&to`, optionally cross-model against hive-default), `POST …/{name}/{version}/confirm` to confirm an ingested model's inferred elements as a new local version (owner, audited `workflow_confirm`), `GET …/{name}/{version}/labels` to preview the labels and commands a model regenerates, and the stage-label provisioner now creates or recolours a bound model's own label vocabulary and re-provisions when the binding changes ([#17620](https://github.com/hivecommons/hive/issues/17620)) diff --git a/dashboard/openapi.json b/dashboard/openapi.json index d4fae455f6..4c1db74093 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -35655,6 +35655,249 @@ } } }, + "/api/workflows/{name}/versions": { + "get": { + "tags": [ + "Workflows" + ], + "summary": "List every saved version of a workflow model", + "description": "Newest save first. hive-default answers its single virtual, read-only entry.", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Versions", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "versions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowEntry" + } + } + } + } + } + } + }, + "404": { + "description": "Unknown model" + }, + "503": { + "description": "No workflow store" + } + } + } + }, + "/api/workflows/{name}/diff": { + "get": { + "tags": [ + "Workflows" + ], + "summary": "Structural diff between two saved workflow model versions", + "description": "Compares spec columns, states (regions flattened), transitions (keyed from>to), labels, derivation rules and meta. from/to are versions of {name}; fromName/toName override the model on either side so a local model can be compared against hive-default.", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "from", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "to", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "fromName", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "toName", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Diff", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "from": { + "$ref": "#/components/schemas/WorkflowEntry" + }, + "to": { + "$ref": "#/components/schemas/WorkflowEntry" + }, + "diff": { + "$ref": "#/components/schemas/WorkflowModelDiff" + } + } + } + } + } + }, + "400": { + "description": "from or to missing, or bad name/version" + }, + "404": { + "description": "Either side not found" + }, + "503": { + "description": "No workflow store" + } + } + } + }, + "/api/workflows/{name}/{version}/confirm": { + "post": { + "tags": [ + "Workflows" + ], + "summary": "Confirm an ingested model's inferred elements as a new local version", + "description": "Owner only. Copies {name}@{version} with every inferred state, event and gate marked confirmed, provenance set to local and metadata.annotations[workflow.hivecommons.dev/confirmed-by] set to the caller, then saves it as the next free integer version. The source version is untouched. Audited as workflow_confirm.", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "version", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "201": { + "description": "Confirmed copy stored", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "entry": { + "$ref": "#/components/schemas/WorkflowEntry" + }, + "confirmed": { + "type": "integer", + "description": "Inferred elements that were confirmed" + }, + "from": { + "type": "string", + "description": "Source name@version" + } + } + } + } + } + }, + "400": { + "description": "Bad name or version" + }, + "403": { + "description": "Not an owner" + }, + "404": { + "description": "Not found" + }, + "409": { + "description": "hive-default is built-in and read-only" + }, + "503": { + "description": "No workflow store" + } + } + } + }, + "/api/workflows/{name}/{version}/labels": { + "get": { + "tags": [ + "Workflows" + ], + "summary": "Preview the labels and commands a workflow model regenerates when bound", + "description": "The label vocabulary the engine reconciles into a bound repository (the model's labels block, stage colour filled in where unset, descriptions clamped), the human-gate verbs each state offers, and the built-in stage label each numbered state maps onto.", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "version", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Preview", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLabelsPreview" + } + } + } + }, + "400": { + "description": "Model does not compile; body carries diagnostics" + }, + "404": { + "description": "Not found" + }, + "503": { + "description": "No workflow store" + } + } + } + }, "/api/workflows/ingest": { "post": { "tags": [ @@ -36131,6 +36374,161 @@ "description": "Compiled, derivation-ready form of a model (hash, states, columns, ordered rules). Never trusted from the wire: the spoke recompiles on save and on bind.", "additionalProperties": true }, + "WorkflowFieldChange": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "from": { + "type": "string" + }, + "to": { + "type": "string" + } + } + }, + "WorkflowChangeSet": { + "type": "object", + "properties": { + "added": { + "type": "array", + "items": { + "type": "string" + } + }, + "removed": { + "type": "array", + "items": { + "type": "string" + } + }, + "changed": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "fields": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowFieldChange" + } + } + } + } + } + } + }, + "WorkflowModelDiff": { + "type": "object", + "description": "Structural difference between two models; deterministic, lists sorted by key.", + "properties": { + "columns": { + "$ref": "#/components/schemas/WorkflowChangeSet" + }, + "states": { + "$ref": "#/components/schemas/WorkflowChangeSet" + }, + "transitions": { + "$ref": "#/components/schemas/WorkflowChangeSet" + }, + "labels": { + "$ref": "#/components/schemas/WorkflowChangeSet" + }, + "rules": { + "$ref": "#/components/schemas/WorkflowChangeSet" + }, + "meta": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowFieldChange" + } + }, + "summary": { + "type": "string" + }, + "empty": { + "type": "boolean" + } + } + }, + "WorkflowLabelDef": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "color": { + "type": "string" + }, + "description": { + "type": "string" + }, + "state": { + "type": "string" + } + } + }, + "WorkflowLabelsPreview": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "hash": { + "type": "string" + }, + "prefix": { + "type": "string" + }, + "labels": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLabelDef" + } + }, + "commands": { + "type": "array", + "items": { + "type": "object", + "properties": { + "state": { + "type": "string" + }, + "verbs": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "stages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "state": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "label": { + "type": "string" + } + } + } + } + } + }, "WorkflowIngestResult": { "type": "object", "properties": { diff --git a/src/docs/design/workflow-models.md b/src/docs/design/workflow-models.md index 1cbe3dae53..888f94e582 100644 --- a/src/docs/design/workflow-models.md +++ b/src/docs/design/workflow-models.md @@ -183,3 +183,76 @@ The tab never binds: binding stays on Settings → Repos so the per-repository d to the repository's other policy. The Activity Monitor's model badge deep-links here via `openWorkflowLibraryEntry(name, version)`. Every HTML builder is a pure function of its inputs so `workflows_library_ui_test.go` runs them under node without a DOM. Editing is phase 4. + +## Versions, diff, confirm and label regeneration (RFC phase 4, backend) + +Phase 4's definition of done is "the TechDocs model can be changed from the diagram and the change +regenerates labels and commands". The backend half gives the editor the primitives for that; the +diagram UI lands separately on top of it. + +### Structural diff — `workflowmodel.Diff` + +`Diff(a, b *Model) ModelDiff` is pure and deterministic: spec only (metadata never counts), +every list sorted by key, the same pair always yields the same JSON. It compares five keyed +collections plus `spec.meta`: + +| Set | Key | Fields compared | +|---|---|---| +| `columns` | column id | label, hint, states, terminal | +| `states` | state id (regions flattened, with `parent`) | label, owner, type, parent, guardRef, pipelines, origin, column, number, kinds, waiting, replies, confidence | +| `transitions` | `from>to` (`from>to@on` when the pair occurs more than once) | on, guardRef, gateRef, note | +| `labels` | label name | color, description, state | +| `rules` | rule id, else `rules[i]` | kind, state, when (rendered predicates), reason | +| `meta` | — | version, author, description, license, source, provenance, derivation mode | + +Each set is `{added, removed, changed:[{key, fields:[{field, from, to}]}]}`; `summary` is one +line (`+2 states, −1 transition, 3 changed`; `no changes` when `empty`). Lists are rendered as +comma-joined strings so a field change is always a flat string pair. + +### Confirm inferred → local — `workflowmodel.Confirm` + +`Confirm(m, by)` returns a deep copy with every `confidence: inferred` element (states at any +depth, events, gates) marked confirmed, `meta.provenance = local`, `meta.version` cleared so the +store assigns the next integer version, and `metadata.annotations["workflow.hivecommons.dev/confirmed-by"]` +set to the caller. `meta.source` is kept: the model still says where it was ingested from. The +input is never modified; `Inferred(m)` counts what is left to confirm. The store gained +`NextVersion(name)` (largest integer version + 1, never a taken one) for this. + +### API + +| Route | Role | Answer | +|---|---|---| +| `GET /api/workflows/{name}/versions` | any | `{versions: []Entry}` newest save first; hive-default returns its one virtual entry; 404 unknown | +| `GET /api/workflows/{name}/diff?from=V1&to=V2[&fromName=&toName=]` | any | `{from: Entry, to: Entry, diff: ModelDiff}`; 400 when `from`/`to` missing, 404 when either side is unknown. `fromName`/`toName` let a local model be diffed against `hive-default` | +| `POST /api/workflows/{name}/{version}/confirm` | owner | 201 `{entry, confirmed, from}` — the confirmed copy saved as the next version; 409 for hive-default (read-only); audited `workflow_confirm` | +| `GET /api/workflows/{name}/{version}/labels` | any | `{name, version, hash, prefix, labels: []LabelDef{name,color,description,state}, commands: [{state, verbs}], stages: [{state, number, label}]}` — the regeneration preview; 400 with diagnostics for a draft that does not compile | + +`labels` is `Profile.LabelDefs(stagelabels.StageColor)`: the model's `spec.labels.entries` with +the stage colour filled in where an entry names none, the state's label as description where an +entry has none, and descriptions clamped to GitHub's limit. `commands` is `Profile.Replies` (the +human-gate verbs per state) in column order. `stages` is the built-in stage label each numbered +state maps onto today, since the engine still writes the built-in family by stage number. + +### Label regeneration on bind + +`automerge.Engine.ensureStageLabels` provisions the built-in family once per repository per +process. It now also asks `stageengine.Options.WorkflowFor` (the P2 lookup cmd/hive wires from +the bindings and the store) for the profile bound to the repository; for a bound, non-hive-default +profile it creates or recolours that profile's `LabelDefs` in the same pass, after the built-in +family, reusing the one label list call. The memo is per repository *and* profile hash +(`StageTracker.ensuredWorkflow`), so a rebinding, an unbind, or a new version of the bound model +changes the hash and the next pass re-lists and provisions only what is missing. No reload hook is +needed: the dashboard's binding edit mutates the live config, `WorkflowFor` reads it on every call, +and the hash comparison does the rest. An unbound repository (or one bound to hive-default) takes +exactly the pre-P4 path: one list, the built-in family, no model labels. + +### Known gaps (phase 4 backend) + +- Labels are only ever created or recoloured, never deleted: unbinding or removing an entry leaves + the label in the repository (same policy as the built-in family). Removal needs an explicit + operator action, not a sweep side effect. +- The engine derives through the built-in stage table by number; a model's own `labels.entries` + are provisioned but not yet written onto items. Writing model labels is the engine half of + phase 4 and follows the diagram editor. +- A model without a `labels` block regenerates nothing (TechDocs as shipped); the preview still + shows its commands and the built-in stages its numbered states land on. diff --git a/src/pkg/dashboard/api_workflows.go b/src/pkg/dashboard/api_workflows.go index c1065c0952..c503cc7c42 100644 --- a/src/pkg/dashboard/api_workflows.go +++ b/src/pkg/dashboard/api_workflows.go @@ -26,6 +26,7 @@ func (s *Server) registerWorkflowRoutes() { s.mux.HandleFunc("GET /api/workflows/{name}/{version}", s.handleWorkflowGet) s.mux.HandleFunc("PUT /api/workflows/{name}/{version}", s.handleWorkflowSave) s.mux.HandleFunc("DELETE /api/workflows/{name}/{version}", s.handleWorkflowDelete) + s.registerWorkflowVersionRoutes() } func (s *Server) workflowStore(w http.ResponseWriter) *wfstore.Store { diff --git a/src/pkg/dashboard/api_workflows_versions.go b/src/pkg/dashboard/api_workflows_versions.go new file mode 100644 index 0000000000..a902ea7646 --- /dev/null +++ b/src/pkg/dashboard/api_workflows_versions.go @@ -0,0 +1,186 @@ +package dashboard + +import ( + "errors" + "fmt" + "net/http" + "time" + + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" + wfstore "github.com/hivecommons/hive/pkg/workflowmodel/store" +) + +// Workflow-model versions, diff, confirm and label preview +// (hivecommons/hive#17620, RFC phase 4, backend). These sit beside the +// library routes in api_workflows.go: reads are open, confirm is +// owner-gated and audited as workflow_confirm. +func (s *Server) registerWorkflowVersionRoutes() { + s.mux.HandleFunc("GET /api/workflows/{name}/versions", s.handleWorkflowVersions) + s.mux.HandleFunc("GET /api/workflows/{name}/diff", s.handleWorkflowDiff) + s.mux.HandleFunc("POST /api/workflows/{name}/{version}/confirm", s.handleWorkflowConfirm) + s.mux.HandleFunc("GET /api/workflows/{name}/{version}/labels", s.handleWorkflowLabels) +} + +// handleWorkflowVersions lists every saved version of a model, newest +// save first; hive-default answers its single virtual entry. +func (s *Server) handleWorkflowVersions(w http.ResponseWriter, r *http.Request) { + st := s.workflowStore(w) + if st == nil { + return + } + entries, err := st.Versions(r.PathValue("name")) + if err != nil { + workflowStoreError(w, err) + return + } + jsonResponse(w, map[string]interface{}{"versions": entries}) +} + +// handleWorkflowDiff compares two saved versions. from/to are versions of +// {name}; fromName/toName override the model name on either side so a +// local model can be compared against hive-default. +func (s *Server) handleWorkflowDiff(w http.ResponseWriter, r *http.Request) { + st := s.workflowStore(w) + if st == nil { + return + } + q := r.URL.Query() + from, to := q.Get("from"), q.Get("to") + if from == "" || to == "" { + jsonError(w, "from and to query parameters are required", http.StatusBadRequest) + return + } + name := r.PathValue("name") + fromName, toName := q.Get("fromName"), q.Get("toName") + if fromName == "" { + fromName = name + } + if toName == "" { + toName = name + } + a, ae, err := st.Get(fromName, from) + if err != nil { + workflowStoreError(w, err) + return + } + b, be, err := st.Get(toName, to) + if err != nil { + workflowStoreError(w, err) + return + } + jsonResponse(w, map[string]interface{}{"from": ae, "to": be, "diff": workflowmodel.Diff(a, b)}) +} + +// handleWorkflowConfirm saves a copy of {name}@{version} with every +// inferred element confirmed and provenance local, as the next integer +// version. hive-default is read-only and answers 409. +func (s *Server) handleWorkflowConfirm(w http.ResponseWriter, r *http.Request) { + if !requireOwnerRole(w, r) { + return + } + st := s.workflowStore(w) + if st == nil { + return + } + name, version := r.PathValue("name"), r.PathValue("version") + if wfstore.IsBuiltin(name) { + jsonError(w, fmt.Sprintf("%s is built-in and read-only; save a copy under another name to edit it", name), http.StatusConflict) + return + } + m, _, err := st.Get(name, version) + if err != nil { + workflowStoreError(w, err) + return + } + inferred := workflowmodel.Inferred(m) + next, err := st.NextVersion(name) + if err != nil { + workflowStoreError(w, err) + return + } + c := workflowmodel.Confirm(m, requestUser(r)) + c.Spec.Meta.Version = next + e, err := st.Save(c, requestUser(r), time.Now().UTC()) + if err != nil { + workflowStoreError(w, err) + return + } + s.auditFromRequest(r, "workflow_confirm", fmt.Sprintf("%s@%s -> %s confirmed=%d compiled=%v", name, version, e.Key(), inferred, e.Compiled), "") + jsonStatusResponse(w, http.StatusCreated, map[string]interface{}{"entry": e, "confirmed": inferred, "from": name + "@" + version}) +} + +// workflowStateCommands is the human-gate verb list one state offers. +type workflowStateCommands struct { + State string `json:"state"` + Verbs []string `json:"verbs"` +} + +// workflowStageLabel is the built-in stage label a numbered state maps +// onto when the model declares no label of its own. +type workflowStageLabel struct { + State string `json:"state"` + Number int `json:"number"` + Label string `json:"label"` +} + +// handleWorkflowLabels previews what binding {name}@{version} regenerates: +// the labels the engine reconciles into a bound repository and the +// commands (human-gate verbs) each state offers. A draft that does not +// compile answers 400 with its diagnostics. +func (s *Server) handleWorkflowLabels(w http.ResponseWriter, r *http.Request) { + st := s.workflowStore(w) + if st == nil { + return + } + name, version := r.PathValue("name"), r.PathValue("version") + p, err := st.Profile(name, version) + if err != nil { + if errors.Is(err, wfstore.ErrNotCompiled) { + _, e, gerr := st.Get(name, version) + if gerr == nil { + jsonStatusResponse(w, http.StatusBadRequest, map[string]interface{}{"error": err.Error(), "diagnostics": e.Diagnostics}) + return + } + } + workflowStoreError(w, err) + return + } + jsonResponse(w, workflowLabelsPreview(p)) +} + +func workflowLabelsPreview(p *workflowmodel.Profile) map[string]interface{} { + labels := p.LabelDefs(stagelabels.StageColor) + if labels == nil { + labels = []workflowmodel.LabelDef{} + } + for i := range labels { + labels[i].Description = stagelabels.ClampLabelDescription(labels[i].Description) + } + commands := []workflowStateCommands{} + stages := []workflowStageLabel{} + for _, col := range p.Columns { + for _, sid := range col.States { + if verbs := p.Replies[sid]; len(verbs) > 0 { + commands = append(commands, workflowStateCommands{State: sid, Verbs: append([]string(nil), verbs...)}) + } + st, ok := p.States[sid] + if !ok || st == nil || st.Lifecycle.Number == 0 { + continue + } + for _, def := range stagelabels.Table { + if def.Number == st.Lifecycle.Number { + stages = append(stages, workflowStageLabel{State: sid, Number: def.Number, Label: def.Stage.Label()}) + break + } + } + } + } + return map[string]interface{}{ + "name": p.Name, "version": p.Version, "hash": p.Hash, + "prefix": p.Labels.Prefix, + "labels": labels, + "commands": commands, + "stages": stages, + } +} diff --git a/src/pkg/dashboard/api_workflows_versions_test.go b/src/pkg/dashboard/api_workflows_versions_test.go new file mode 100644 index 0000000000..6b0f72061d --- /dev/null +++ b/src/pkg/dashboard/api_workflows_versions_test.go @@ -0,0 +1,219 @@ +package dashboard + +import ( + "encoding/json" + "net/http" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" + "github.com/hivecommons/hive/pkg/workflowmodel/hivedefault" + wfstore "github.com/hivecommons/hive/pkg/workflowmodel/store" +) + +func TestWorkflowVersionRoutesNeedStore(t *testing.T) { + s := workflowTestServer(t, false) + for _, c := range []struct{ method, path string }{ + {http.MethodGet, "/api/workflows/x/versions"}, + {http.MethodGet, "/api/workflows/x/diff?from=1&to=2"}, + {http.MethodPost, "/api/workflows/x/1/confirm"}, + {http.MethodGet, "/api/workflows/x/1/labels"}, + } { + if rec := wfReq(s, c.method, c.path, nil, true); rec.Code != http.StatusServiceUnavailable { + t.Fatalf("%s %s: %d %s", c.method, c.path, rec.Code, rec.Body) + } + } + s = workflowTestServer(t, true) + if rec := wfReq(s, http.MethodPost, "/api/workflows/x/1/confirm", nil, false); rec.Code != http.StatusForbidden { + t.Fatalf("confirm owner gate: %d", rec.Code) + } +} + +func TestWorkflowVersionsAndDiff(t *testing.T) { + s := workflowTestServer(t, true) + m := techdocsModel(t) + if rec := wfReq(s, http.MethodPost, "/api/workflows", m, true); rec.Code != http.StatusCreated { + t.Fatal(rec.Body.String()) + } + m2 := techdocsModel(t) + m2.Spec.Meta.Version = "2" + m2.Spec.States[0].Label = "Requested!" + m2.Spec.States = append(m2.Spec.States, workflowmodel.State{ID: "extra", Label: "Extra", Owner: workflowmodel.OwnerHuman}) + if rec := wfReq(s, http.MethodPost, "/api/workflows", m2, true); rec.Code != http.StatusCreated { + t.Fatal(rec.Body.String()) + } + + rec := wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/versions", nil, false) + var vs struct{ Versions []wfstore.Entry } + if rec.Code != 200 || json.Unmarshal(rec.Body.Bytes(), &vs) != nil || len(vs.Versions) != 2 { + t.Fatalf("%d %s", rec.Code, rec.Body) + } + if rec := wfReq(s, http.MethodGet, "/api/workflows/ghost/versions", nil, false); rec.Code != http.StatusNotFound { + t.Fatalf("unknown: %d", rec.Code) + } + rec = wfReq(s, http.MethodGet, "/api/workflows/hive-default/versions", nil, false) + if rec.Code != 200 || json.Unmarshal(rec.Body.Bytes(), &vs) != nil || len(vs.Versions) != 1 || !vs.Versions[0].ReadOnly { + t.Fatalf("builtin: %d %s", rec.Code, rec.Body) + } + + for _, bad := range []string{"", "?from=1", "?to=2"} { + if rec := wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/diff"+bad, nil, false); rec.Code != http.StatusBadRequest { + t.Fatalf("diff %q: %d", bad, rec.Code) + } + } + if rec := wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/diff?from=1&to=9", nil, false); rec.Code != http.StatusNotFound { + t.Fatalf("diff missing to: %d", rec.Code) + } + if rec := wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/diff?from=9&to=1", nil, false); rec.Code != http.StatusNotFound { + t.Fatalf("diff missing from: %d", rec.Code) + } + rec = wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/diff?from=1&to=2", nil, false) + var d struct { + From, To wfstore.Entry + Diff workflowmodel.ModelDiff + } + if rec.Code != 200 || json.Unmarshal(rec.Body.Bytes(), &d) != nil { + t.Fatalf("%d %s", rec.Code, rec.Body) + } + if d.From.Version != "1" || d.To.Version != "2" || d.Diff.Empty || len(d.Diff.States.Added) != 1 || len(d.Diff.States.Changed) != 1 || d.Diff.Summary != "+1 state, 2 changed" { + t.Fatalf("diff %+v", d.Diff) + } + // same version both sides is empty; cross-model diff against hive-default works + rec = wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/diff?from=1&to=1", nil, false) + if rec.Code != 200 || json.Unmarshal(rec.Body.Bytes(), &d) != nil || !d.Diff.Empty { + t.Fatalf("%d %s", rec.Code, rec.Body) + } + rec = wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/diff?from=1&toName=hive-default&to="+hivedefault.Version, nil, false) + if rec.Code != 200 || json.Unmarshal(rec.Body.Bytes(), &d) != nil || d.To.Name != hivedefault.Name || len(d.Diff.States.Added) == 0 { + t.Fatalf("%d %s", rec.Code, rec.Body) + } +} + +func TestWorkflowConfirm(t *testing.T) { + s := workflowTestServer(t, true) + m := techdocsModel(t) + m.Spec.Meta.Provenance = workflowmodel.ProvenanceIngestedUnreviewed + m.Spec.States[0].Lifecycle.Confidence = workflowmodel.ConfidenceInferred + m.Spec.Events[0].Confidence = workflowmodel.ConfidenceInferred + if rec := wfReq(s, http.MethodPost, "/api/workflows", m, true); rec.Code != http.StatusCreated { + t.Fatal(rec.Body.String()) + } + if rec := wfReq(s, http.MethodPost, "/api/workflows/hive-default/1/confirm", nil, true); rec.Code != http.StatusConflict || !strings.Contains(rec.Body.String(), "read-only") { + t.Fatalf("builtin: %d %s", rec.Code, rec.Body) + } + if rec := wfReq(s, http.MethodPost, "/api/workflows/cncf-techdocs/9/confirm", nil, true); rec.Code != http.StatusNotFound { + t.Fatalf("missing: %d", rec.Code) + } + if rec := wfReq(s, http.MethodPost, "/api/workflows/Bad%20Name/1/confirm", nil, true); rec.Code != http.StatusBadRequest { + t.Fatalf("bad name: %d", rec.Code) + } + + rec := wfReq(s, http.MethodPost, "/api/workflows/cncf-techdocs/1/confirm", nil, true) + var out struct { + Entry wfstore.Entry + Confirmed int + From string + } + if rec.Code != http.StatusCreated || json.Unmarshal(rec.Body.Bytes(), &out) != nil { + t.Fatalf("%d %s", rec.Code, rec.Body) + } + if out.Entry.Version != "2" || out.Entry.Provenance != workflowmodel.ProvenanceLocal || out.Confirmed != 2 || out.From != "cncf-techdocs@1" || !out.Entry.Compiled || out.Entry.SavedBy != "andy" { + t.Fatalf("%+v", out) + } + for _, dg := range out.Entry.Diagnostics { + if dg.Code == workflowmodel.CodeInferred { + t.Fatalf("confirmed version still warns inferred: %+v", out.Entry.Diagnostics) + } + } + saved, _, err := s.deps.WorkflowStore.Get("cncf-techdocs", "2") + if err != nil || workflowmodel.Inferred(saved) != 0 || saved.Metadata.Annotations[workflowmodel.AnnotationConfirmedBy] != "andy" { + t.Fatalf("%v %+v", err, saved.Metadata) + } + // the original is untouched + orig, _, err := s.deps.WorkflowStore.Get("cncf-techdocs", "1") + if err != nil || workflowmodel.Inferred(orig) != 2 { + t.Fatalf("%v inferred=%d", err, workflowmodel.Inferred(orig)) + } + // confirming again allocates the next version + rec = wfReq(s, http.MethodPost, "/api/workflows/cncf-techdocs/2/confirm", nil, true) + if rec.Code != http.StatusCreated || json.Unmarshal(rec.Body.Bytes(), &out) != nil || out.Entry.Version != "3" || out.Confirmed != 0 { + t.Fatalf("%d %s", rec.Code, rec.Body) + } + if !auditHasAction(t, s, "workflow_confirm") { + t.Fatal("no workflow_confirm audit entry") + } +} + +func auditHasAction(t *testing.T, s *Server, action string) bool { + t.Helper() + rec := wfReq(s, http.MethodGet, "/api/audit?limit=50", nil, true) + if rec.Code != 200 { + t.Fatalf("audit: %d %s", rec.Code, rec.Body) + } + return strings.Contains(rec.Body.String(), `"`+action+`"`) +} + +func TestWorkflowLabelsPreview(t *testing.T) { + s := workflowTestServer(t, true) + m := techdocsModel(t) + m.Spec.Labels = workflowmodel.LabelSet{Prefix: "docs", Entries: []workflowmodel.LabelEntry{ + {Name: "docs/010-requested", State: "requested"}, + {Name: "docs/020-analysing", Color: "123456", Description: strings.Repeat("x", 200), State: "analysing"}, + }} + if rec := wfReq(s, http.MethodPost, "/api/workflows", m, true); rec.Code != http.StatusCreated { + t.Fatal(rec.Body.String()) + } + rec := wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/1/labels", nil, false) + var out struct { + Name, Version, Prefix string + Labels []workflowmodel.LabelDef + Commands []struct { + State string + Verbs []string + } + Stages []struct { + State string + Label string + } + } + if rec.Code != 200 || json.Unmarshal(rec.Body.Bytes(), &out) != nil { + t.Fatalf("%d %s", rec.Code, rec.Body) + } + if out.Name != "cncf-techdocs" || out.Prefix != "docs" || len(out.Labels) != 2 { + t.Fatalf("%+v", out) + } + if out.Labels[0].Color != stagelabels.StageColor || out.Labels[0].Description != m.Spec.States[0].Label || out.Labels[1].Color != "123456" || len(out.Labels[1].Description) >= 200 { + t.Fatalf("labels %+v", out.Labels) + } + verbs := map[string][]string{} + for _, c := range out.Commands { + verbs[c.State] = c.Verbs + } + if len(verbs["analysing"]) != 1 || verbs["analysing"][0] != "hand back" || len(verbs["requested"]) != 0 { + t.Fatalf("commands %+v", out.Commands) + } + if len(out.Stages) == 0 || out.Stages[0].Label == "" { + t.Fatalf("stages %+v", out.Stages) + } + + // hive-default previews the built-in family + rec = wfReq(s, http.MethodGet, "/api/workflows/hive-default/"+hivedefault.Version+"/labels", nil, false) + if rec.Code != 200 || json.Unmarshal(rec.Body.Bytes(), &out) != nil || len(out.Labels) == 0 || out.Labels[0].Color != stagelabels.StageColor { + t.Fatalf("builtin: %d %s", rec.Code, rec.Body) + } + if rec := wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/9/labels", nil, false); rec.Code != http.StatusNotFound { + t.Fatalf("missing: %d", rec.Code) + } + // a draft that does not compile answers 400 with its diagnostics + draft := techdocsModel(t) + draft.Spec.Meta.Version = "draft" + draft.Spec.Gates[0].ReleasedBy = "" + if rec := wfReq(s, http.MethodPost, "/api/workflows", draft, true); rec.Code != http.StatusCreated { + t.Fatal(rec.Body.String()) + } + rec = wfReq(s, http.MethodGet, "/api/workflows/cncf-techdocs/draft/labels", nil, false) + if rec.Code != http.StatusBadRequest || !strings.Contains(rec.Body.String(), `"diagnostics"`) { + t.Fatalf("draft: %d %s", rec.Code, rec.Body) + } +} diff --git a/src/pkg/github/automerge/automerge_stage_labels.go b/src/pkg/github/automerge/automerge_stage_labels.go index 3ec17754e7..1c067eb514 100644 --- a/src/pkg/github/automerge/automerge_stage_labels.go +++ b/src/pkg/github/automerge/automerge_stage_labels.go @@ -35,6 +35,8 @@ import ( "github.com/hivecommons/hive/pkg/stageengine" "github.com/hivecommons/hive/pkg/stageengine/prstage" "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" + "github.com/hivecommons/hive/pkg/workflowmodel/hivedefault" ) // StageLabelPolicy is the live `governor.labels.stage` policy. @@ -261,7 +263,11 @@ type StageTracker struct { obs map[string]map[string]stageObservation // key → lane → observation details map[string]stageDetail // key → detail noted by trySweep* ensured map[string]bool // repo → labels provisioned this process - checks map[string]humanChecksEntry // key → head check digest (human routing) + // ensuredWorkflow is the hash of the bound workflow model whose + // labels were provisioned per repo; a rebinding changes the hash + // and the next pass re-provisions (hivecommons/hive#17620, P4). + ensuredWorkflow map[string]string + checks map[string]humanChecksEntry // key → head check digest (human routing) // superseded remembers when the hive-authored superseded check last // ran per key+head, so a PR that legitimately sits at 085 is not // re-read every pass. @@ -270,7 +276,7 @@ type StageTracker struct { // NewStageTracker returns an empty tracker. func NewStageTracker() *StageTracker { - return &StageTracker{obs: map[string]map[string]stageObservation{}, details: map[string]stageDetail{}, ensured: map[string]bool{}, checks: map[string]humanChecksEntry{}, superseded: map[string]time.Time{}} + return &StageTracker{obs: map[string]map[string]stageObservation{}, details: map[string]stageDetail{}, ensured: map[string]bool{}, ensuredWorkflow: map[string]string{}, checks: map[string]humanChecksEntry{}, superseded: map[string]time.Time{}} } var sharedStageTracker = NewStageTracker() @@ -1643,10 +1649,21 @@ func (f *engineStatusForge) DeleteComment(ctx context.Context, id int64) error { // missing or whose colour drifted from the table. A PATCH keeps the label on // every PR wearing it, so a pre-existing `dco` label is recoloured in place // rather than re-added. +// +// A repository bound to a workflow model (hivecommons/hive#17620, P4) also +// gets that model's own label vocabulary (Profile.LabelDefs) created or +// recoloured, memoised by the model's hash so a rebinding — or a new +// version of the bound model — re-provisions on the next pass. An unbound +// repository takes exactly the built-in path. func (c *Engine) ensureStageLabels(ctx context.Context, owner, repo string, tracker *StageTracker, kinds authorkind.Names) error { full := strings.ToLower(owner + "/" + repo) + var model []workflowmodel.LabelDef + modelHash := "" + if p := c.workflowProfile(owner, repo); p != nil { + model, modelHash = p.LabelDefs(stagelabels.StageColor), p.Hash + } tracker.mu.Lock() - done := tracker.ensured[full] + done := tracker.ensured[full] && tracker.ensuredWorkflow[full] == modelHash tracker.mu.Unlock() if done { return nil @@ -1685,27 +1702,63 @@ func (c *Engine) ensureStageLabels(ctx context.Context, owner, repo string, trac } existing[strings.ToLower(stage.Label())] = renamed } - for _, def := range stagelabels.LabelDefsFor(kinds) { - cur, ok := existing[strings.ToLower(def.Name)] + ensure := func(name, color, description string) error { + cur, ok := existing[strings.ToLower(name)] switch { case !ok: - _, _, err := c.gh.Issues.CreateLabel(ctx, owner, repo, &gh.Label{Name: gh.Ptr(def.Name), Color: gh.Ptr(def.Color), Description: gh.Ptr(stagelabels.ClampLabelDescription(def.Description))}) + created, _, err := c.gh.Issues.CreateLabel(ctx, owner, repo, &gh.Label{Name: gh.Ptr(name), Color: gh.Ptr(color), Description: gh.Ptr(stagelabels.ClampLabelDescription(description))}) if err != nil && !isGitHubStatus(err, http.StatusUnprocessableEntity) { - return fmt.Errorf("creating label %s in %s: %w", def.Name, full, err) + return fmt.Errorf("creating label %s in %s: %w", name, full, err) } - case !strings.EqualFold(cur.GetColor(), def.Color): - _, _, err := c.gh.Issues.EditLabel(ctx, owner, repo, cur.GetName(), &gh.Label{Name: gh.Ptr(def.Name), Color: gh.Ptr(def.Color), Description: gh.Ptr(stagelabels.ClampLabelDescription(def.Description))}) + if created == nil { + created = &gh.Label{Name: gh.Ptr(name), Color: gh.Ptr(color)} + } + existing[strings.ToLower(name)] = created + case !strings.EqualFold(cur.GetColor(), color): + _, _, err := c.gh.Issues.EditLabel(ctx, owner, repo, cur.GetName(), &gh.Label{Name: gh.Ptr(name), Color: gh.Ptr(color), Description: gh.Ptr(stagelabels.ClampLabelDescription(description))}) if err != nil { - return fmt.Errorf("recolouring label %s in %s: %w", def.Name, full, err) + return fmt.Errorf("recolouring label %s in %s: %w", name, full, err) } + cur.Color = gh.Ptr(color) + } + return nil + } + for _, def := range stagelabels.LabelDefsFor(kinds) { + if err := ensure(def.Name, def.Color, def.Description); err != nil { + return err + } + } + for _, def := range model { + if err := ensure(def.Name, def.Color, def.Description); err != nil { + return err } } tracker.mu.Lock() tracker.ensured[full] = true + if tracker.ensuredWorkflow == nil { + tracker.ensuredWorkflow = map[string]string{} + } + tracker.ensuredWorkflow[full] = modelHash tracker.mu.Unlock() return nil } +// workflowProfile is the compiled workflow model bound to owner/repo, or +// nil when the engine has no stage-engine options, no lookup (P2's +// Options.WorkflowFor), the repository is unbound, or the binding is +// hive-default (whose labels are the built-in family already provisioned +// above). +func (c *Engine) workflowProfile(owner, repo string) *workflowmodel.Profile { + if c == nil || c.stageEngine == nil || c.stageEngine.WorkflowFor == nil { + return nil + } + p := c.stageEngine.WorkflowFor(owner, repo) + if p == nil || p.Name == hivedefault.Name { + return nil + } + return p +} + // ApplyStageLabels runs the reconcile pass on a one-shot engine. The // tracker and store are process-shared, so observations recorded by the // lanes' own one-shot engines earlier in the cycle are what it applies. diff --git a/src/pkg/github/automerge/automerge_stage_labels_workflow_test.go b/src/pkg/github/automerge/automerge_stage_labels_workflow_test.go new file mode 100644 index 0000000000..943e275af4 --- /dev/null +++ b/src/pkg/github/automerge/automerge_stage_labels_workflow_test.go @@ -0,0 +1,150 @@ +package automerge + +import ( + "context" + "encoding/json" + "os" + "slices" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/authorkind" + hgithub "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/stageengine" + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" + "github.com/hivecommons/hive/pkg/workflowmodel/hivedefault" +) + +func workflowTestProfile(t *testing.T, labels ...workflowmodel.LabelEntry) *workflowmodel.Profile { + t.Helper() + b, err := os.ReadFile("../../workflowmodel/testdata/models/techdocs.json") + if err != nil { + t.Fatal(err) + } + var m workflowmodel.Model + if err := json.Unmarshal(b, &m); err != nil { + t.Fatal(err) + } + m.Spec.Labels = workflowmodel.LabelSet{Prefix: "docs", Entries: labels} + p, _, err := workflowmodel.Compile(&m) + if err != nil { + t.Fatal(err) + } + return p +} + +// newWorkflowStageEngine is newStageEngine with a WorkflowFor lookup the +// test controls per call. +func newWorkflowStageEngine(t *testing.T, apiURL string, lookup func(owner, repo string) *workflowmodel.Profile) (*Engine, *StageTracker) { + t.Helper() + clock := &contributorLaneClock{at: time.Date(2026, 11, 11, 12, 0, 0, 0, time.UTC)} + client := hgithub.NewClient("token", "acme", []string{"widget"}, nil, apiURL) + tracker := NewStageTracker() + e := New(client, Options{ + Now: clock.now, + StageTracker: tracker, + StageEngine: &stageengine.Options{WorkflowFor: lookup}, + }) + return e, tracker +} + +func TestEnsureStageLabelsUnboundRepoIsUnchanged(t *testing.T) { + ctx := context.Background() + for name, lookup := range map[string]func(owner, repo string) *workflowmodel.Profile{ + "no lookup": nil, + "unbound": func(string, string) *workflowmodel.Profile { return nil }, + "hive-default": func(string, string) *workflowmodel.Profile { return hivedefault.Profile() }, + "other repo": func(_, repo string) *workflowmodel.Profile { + if repo == "other" { + return workflowTestProfile(t, workflowmodel.LabelEntry{Name: "docs/x"}) + } + return nil + }, + } { + t.Run(name, func(t *testing.T) { + api := &stageAPI{labels: map[string]string{"bug": "ff0000"}} + srv := newStageAPI(t, api) + defer srv.Close() + e, tracker := newWorkflowStageEngine(t, srv.URL, lookup) + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + if len(api.creates) != len(stagelabels.AllLabelDefs()) || api.lists != 1 || len(api.edits) != 0 { + t.Fatalf("creates=%d lists=%d edits=%v", len(api.creates), api.lists, api.edits) + } + for _, c := range api.creates { + if c == "docs/x" { + t.Fatalf("model label leaked into an unbound repo: %v", api.creates) + } + } + // memoised: a second call does nothing + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil || api.lists != 1 { + t.Fatalf("second call: err=%v lists=%d", err, api.lists) + } + }) + } +} + +func TestEnsureStageLabelsProvisionsBoundModelAndReprovisionsOnRebind(t *testing.T) { + ctx := context.Background() + api := &stageAPI{labels: map[string]string{"docs/020-analysing": "000000"}} + srv := newStageAPI(t, api) + defer srv.Close() + + v1 := workflowTestProfile(t, + workflowmodel.LabelEntry{Name: "docs/010-requested", State: "requested"}, + workflowmodel.LabelEntry{Name: "docs/020-analysing", Color: "123456", Description: "analysing", State: "analysing"}, + ) + current := v1 + e, tracker := newWorkflowStageEngine(t, srv.URL, func(string, string) *workflowmodel.Profile { return current }) + + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + if api.lists != 1 || !slices.Contains(api.creates, "docs/010-requested") || len(api.creates) != len(stagelabels.AllLabelDefs())+1 { + t.Fatalf("lists=%d creates=%v", api.lists, api.creates) + } + if api.labels["docs/010-requested"] != stagelabels.StageColor || api.labels["docs/020-analysing"] != "123456" || !slices.Contains(api.edits, "docs/020-analysing=123456") { + t.Fatalf("labels=%v edits=%v", api.labels, api.edits) + } + if tracker.ensuredWorkflow["acme/widget"] != v1.Hash { + t.Fatalf("memo %q", tracker.ensuredWorkflow["acme/widget"]) + } + + // same binding: memoised, no second list + api.reset() + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil || api.lists != 1 || api.writes() != 0 || len(api.creates)+len(api.edits) != 0 { + t.Fatalf("idempotent: err=%v lists=%d writes=%d creates=%v edits=%v", err, api.lists, api.writes(), api.creates, api.edits) + } + + // rebind to a new version with one more label: re-list, create only the new one + current = workflowTestProfile(t, + workflowmodel.LabelEntry{Name: "docs/010-requested", State: "requested"}, + workflowmodel.LabelEntry{Name: "docs/020-analysing", Color: "123456", Description: "analysing", State: "analysing"}, + workflowmodel.LabelEntry{Name: "docs/045-analysis-review", State: "analysis-review"}, + ) + if current.Hash == v1.Hash { + t.Fatal("fixture: hash did not change") + } + api.reset() + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + if api.lists != 2 || !slices.Equal(api.creates, []string{"docs/045-analysis-review"}) || len(api.edits) != 0 { + t.Fatalf("rebind: lists=%d creates=%v edits=%v", api.lists, api.creates, api.edits) + } + if tracker.ensuredWorkflow["acme/widget"] != current.Hash { + t.Fatalf("memo %q", tracker.ensuredWorkflow["acme/widget"]) + } + + // unbind: re-list once (hash changes to ""), nothing to create; model labels are left in place + current = nil + api.reset() + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil || api.lists != 3 || len(api.creates)+len(api.edits) != 0 { + t.Fatalf("unbind: err=%v lists=%d creates=%v edits=%v", err, api.lists, api.creates, api.edits) + } + if _, ok := api.labels["docs/045-analysis-review"]; !ok { + t.Fatal("unbind deleted a model label") + } +} diff --git a/src/pkg/workflowmodel/confirm.go b/src/pkg/workflowmodel/confirm.go new file mode 100644 index 0000000000..1fdddbb240 --- /dev/null +++ b/src/pkg/workflowmodel/confirm.go @@ -0,0 +1,120 @@ +package workflowmodel + +import "encoding/json" + +// AnnotationConfirmedBy records who confirmed an ingested model's inferred +// elements (Confirm). It lives in metadata.annotations so the spec hash +// stays a function of the spec alone. +const AnnotationConfirmedBy = "workflow.hivecommons.dev/confirmed-by" + +// Confirm returns a deep copy of m in which every inferred element +// (states at any depth, events, gates) is marked confirmed, provenance is +// local and the version is cleared so the store assigns the next one. The +// source is kept: the model still says where it was ingested from. m is +// not modified. +func Confirm(m *Model, by string) *Model { + if m == nil { + return nil + } + out := Clone(m) + var walk func(states []State) + walk = func(states []State) { + for i := range states { + states[i].Lifecycle.Confidence = ConfidenceConfirmed + walk(states[i].Regions) + } + } + walk(out.Spec.States) + for i := range out.Spec.Events { + out.Spec.Events[i].Confidence = ConfidenceConfirmed + } + for i := range out.Spec.Gates { + out.Spec.Gates[i].Confidence = ConfidenceConfirmed + } + out.Spec.Meta.Provenance = ProvenanceLocal + out.Spec.Meta.Version = "" + if by != "" { + if out.Metadata.Annotations == nil { + out.Metadata.Annotations = map[string]string{} + } + out.Metadata.Annotations[AnnotationConfirmedBy] = by + } + return out +} + +// Clone returns a deep copy of m via its JSON form. +func Clone(m *Model) *Model { + if m == nil { + return nil + } + b, _ := json.Marshal(m) + var out Model + _ = json.Unmarshal(b, &out) + return &out +} + +// Inferred counts the elements a human has not confirmed yet. +func Inferred(m *Model) int { + if m == nil { + return 0 + } + n := 0 + var walk func(states []State) + walk = func(states []State) { + for _, s := range states { + if s.Lifecycle.Confidence == ConfidenceInferred { + n++ + } + walk(s.Regions) + } + } + walk(m.Spec.States) + for _, e := range m.Spec.Events { + if e.Confidence == ConfidenceInferred { + n++ + } + } + for _, g := range m.Spec.Gates { + if g.Confidence == ConfidenceInferred { + n++ + } + } + return n +} + +// LabelDef is one label a Profile asks the engine to reconcile into a +// bound repository. +type LabelDef struct { + Name string `json:"name"` + Color string `json:"color"` + Description string `json:"description,omitempty"` + State string `json:"state,omitempty"` +} + +// LabelDefs is the label vocabulary the profile reconciles: its label +// entries with defaultColor filled in where an entry names none and the +// state's label as description where an entry has none. Entries are +// returned in declaration order; a model with no labels block regenerates +// nothing and keeps using the built-in family by stage number. +func (p *Profile) LabelDefs(defaultColor string) []LabelDef { + if p == nil { + return nil + } + out := make([]LabelDef, 0, len(p.Labels.Entries)) + for _, e := range p.Labels.Entries { + if e.Name == "" { + continue + } + d := LabelDef{Name: e.Name, Color: e.Color, Description: e.Description, State: e.State} + if d.Color == "" { + d.Color = defaultColor + } + if d.Description == "" && e.State != "" { + if s, ok := p.States[e.State]; ok && s != nil { + d.Description = s.Label + } + } + out = append(out, d) + } + return out +} diff --git a/src/pkg/workflowmodel/diff.go b/src/pkg/workflowmodel/diff.go new file mode 100644 index 0000000000..9a21eddb0a --- /dev/null +++ b/src/pkg/workflowmodel/diff.go @@ -0,0 +1,266 @@ +package workflowmodel + +import ( + "fmt" + "sort" + "strconv" + "strings" +) + +// ModelDiff is the structural difference between two models +// (hivecommons/hive#17620, RFC phase 4). It is computed from the spec +// only, never from metadata, and is deterministic: the same pair always +// produces the same diff, with every list sorted by key. +type ModelDiff struct { + // Columns are keyed by column id. + Columns ChangeSet `json:"columns"` + // States are keyed by state id; regions are flattened like Compile. + States ChangeSet `json:"states"` + // Transitions are keyed "from>to" ("from>to@on" when a pair occurs + // more than once). + Transitions ChangeSet `json:"transitions"` + // Labels are keyed by label name. + Labels ChangeSet `json:"labels"` + // Rules are keyed by rule id, or "rules[i]" for an unnamed rule. + Rules ChangeSet `json:"rules"` + // Meta lists the spec.meta fields that differ. + Meta []FieldChange `json:"meta,omitempty"` + // Summary is a one-line human description ("+2 states, −1 + // transition, 3 changed"; "no changes" when Empty). + Summary string `json:"summary"` + Empty bool `json:"empty"` +} + +// ChangeSet is the diff of one keyed collection. +type ChangeSet struct { + Added []string `json:"added,omitempty"` + Removed []string `json:"removed,omitempty"` + Changed []ItemChange `json:"changed,omitempty"` +} + +// Len is the number of items added, removed or changed. +func (c ChangeSet) Len() int { return len(c.Added) + len(c.Removed) + len(c.Changed) } + +// ItemChange is one item present in both models whose fields differ. +type ItemChange struct { + Key string `json:"key"` + Fields []FieldChange `json:"fields"` +} + +// FieldChange is one scalar field that differs. Lists are rendered as +// comma-joined strings so the diff stays flat and JSON-friendly. +type FieldChange struct { + Field string `json:"field"` + From string `json:"from"` + To string `json:"to"` +} + +// Diff compares a and b structurally. Either may be nil, which is treated +// as an empty model. +func Diff(a, b *Model) ModelDiff { + if a == nil { + a = &Model{} + } + if b == nil { + b = &Model{} + } + d := ModelDiff{ + Columns: diffItems(columnItems(a), columnItems(b)), + States: diffItems(stateItems(a), stateItems(b)), + Transitions: diffItems(transitionItems(a), transitionItems(b)), + Labels: diffItems(labelItems(a), labelItems(b)), + Rules: diffItems(ruleItems(a), ruleItems(b)), + Meta: fieldChanges(metaFields(a), metaFields(b)), + } + d.Empty = d.Columns.Len()+d.States.Len()+d.Transitions.Len()+d.Labels.Len()+d.Rules.Len()+len(d.Meta) == 0 + d.Summary = d.summary() + return d +} + +func (d ModelDiff) summary() string { + if d.Empty { + return "no changes" + } + var parts []string + changed := len(d.Meta) + for _, c := range []struct { + noun string + set ChangeSet + }{ + {"column", d.Columns}, {"state", d.States}, {"transition", d.Transitions}, {"label", d.Labels}, {"rule", d.Rules}, + } { + if n := len(c.set.Added); n > 0 { + parts = append(parts, "+"+strconv.Itoa(n)+" "+plural(c.noun, n)) + } + if n := len(c.set.Removed); n > 0 { + parts = append(parts, "−"+strconv.Itoa(n)+" "+plural(c.noun, n)) + } + changed += len(c.set.Changed) + } + if changed > 0 { + parts = append(parts, strconv.Itoa(changed)+" changed") + } + return strings.Join(parts, ", ") +} + +func plural(noun string, n int) string { + if n == 1 { + return noun + } + return noun + "s" +} + +// item is one keyed element with its comparable fields in a fixed order. +type item struct { + key string + fields []field +} + +type field struct{ name, value string } + +func diffItems(a, b []item) ChangeSet { + var cs ChangeSet + am := map[string]item{} + for _, it := range a { + am[it.key] = it + } + bm := map[string]item{} + for _, it := range b { + bm[it.key] = it + } + for k := range am { + if _, ok := bm[k]; !ok { + cs.Removed = append(cs.Removed, k) + } + } + for k, bi := range bm { + ai, ok := am[k] + if !ok { + cs.Added = append(cs.Added, k) + continue + } + if fc := fieldChanges(ai.fields, bi.fields); len(fc) > 0 { + cs.Changed = append(cs.Changed, ItemChange{Key: k, Fields: fc}) + } + } + sort.Strings(cs.Added) + sort.Strings(cs.Removed) + sort.Slice(cs.Changed, func(i, j int) bool { return cs.Changed[i].Key < cs.Changed[j].Key }) + return cs +} + +// fieldChanges compares two field lists by name; a field present on one +// side only is reported against the empty string. +func fieldChanges(a, b []field) []FieldChange { + av := map[string]string{} + for _, f := range a { + av[f.name] = f.value + } + var out []FieldChange + seen := map[string]bool{} + for _, f := range b { + seen[f.name] = true + if av[f.name] != f.value { + out = append(out, FieldChange{Field: f.name, From: av[f.name], To: f.value}) + } + } + for _, f := range a { + if !seen[f.name] && f.value != "" { + out = append(out, FieldChange{Field: f.name, From: f.value, To: ""}) + } + } + return out +} + +func join(ss []string) string { return strings.Join(ss, ",") } + +func joinKinds(ks []ItemKind) string { + out := make([]string, len(ks)) + for i, k := range ks { + out[i] = string(k) + } + return join(out) +} + +func columnItems(m *Model) []item { + var out []item + for _, c := range m.Spec.Columns { + out = append(out, item{key: c.ID, fields: []field{ + {"label", c.Label}, {"hint", c.Hint}, {"states", join(c.States)}, {"terminal", strconv.FormatBool(c.Terminal)}, + }}) + } + return out +} + +func stateItems(m *Model) []item { + var out []item + var walk func(states []State, parent string) + walk = func(states []State, parent string) { + for _, s := range states { + out = append(out, item{key: s.ID, fields: []field{ + {"label", s.Label}, {"owner", string(s.Owner)}, {"type", string(s.Type)}, {"parent", parent}, + {"guardRef", s.GuardRef}, {"pipelines", join(s.Pipelines)}, {"origin", string(s.Origin)}, + {"column", s.Lifecycle.Column}, {"number", strconv.Itoa(s.Lifecycle.Number)}, + {"kinds", joinKinds(s.Lifecycle.Kinds)}, {"waiting", join(s.Lifecycle.Waiting)}, + {"replies", join(s.Lifecycle.Replies)}, {"confidence", string(s.Lifecycle.Confidence)}, + }}) + walk(s.Regions, s.ID) + } + } + walk(m.Spec.States, "") + return out +} + +func transitionItems(m *Model) []item { + pairs := map[string]int{} + for _, t := range m.Spec.Transitions { + pairs[t.From+">"+t.To]++ + } + var out []item + for _, t := range m.Spec.Transitions { + key := t.From + ">" + t.To + if pairs[key] > 1 { + key += "@" + t.On + } + out = append(out, item{key: key, fields: []field{ + {"on", t.On}, {"guardRef", t.GuardRef}, {"gateRef", t.GateRef}, {"note", t.Note}, + }}) + } + return out +} + +func labelItems(m *Model) []item { + var out []item + for _, l := range m.Spec.Labels.Entries { + out = append(out, item{key: l.Name, fields: []field{ + {"color", l.Color}, {"description", l.Description}, {"state", l.State}, + }}) + } + return out +} + +func ruleItems(m *Model) []item { + var out []item + for i, r := range m.Spec.Derivation.Rules { + key := r.ID + if key == "" { + key = fmt.Sprintf("rules[%d]", i) + } + preds := make([]string, len(r.When)) + for j, p := range r.When { + preds[j] = p.Fact + " " + string(p.Op) + " " + p.Value + } + out = append(out, item{key: key, fields: []field{ + {"kind", string(r.Kind)}, {"state", r.State}, {"when", strings.Join(preds, "; ")}, {"reason", r.Reason}, + }}) + } + return out +} + +func metaFields(m *Model) []field { + mt := m.Spec.Meta + return []field{ + {"version", mt.Version}, {"author", mt.Author}, {"description", mt.Description}, {"license", mt.License}, + {"source", string(mt.Source)}, {"provenance", string(mt.Provenance)}, {"mode", string(m.Spec.Derivation.Mode)}, + } +} diff --git a/src/pkg/workflowmodel/diff_test.go b/src/pkg/workflowmodel/diff_test.go new file mode 100644 index 0000000000..479a50b4ca --- /dev/null +++ b/src/pkg/workflowmodel/diff_test.go @@ -0,0 +1,200 @@ +package workflowmodel + +import ( + "encoding/json" + "reflect" + "strconv" + "strings" + "testing" +) + +func TestDiffIdenticalIsEmpty(t *testing.T) { + a := techdocs(t) + d := Diff(a, Clone(a)) + if !d.Empty || d.Summary != "no changes" { + t.Fatalf("diff of identical models: %+v", d) + } + if nd := Diff(nil, nil); !nd.Empty { + t.Fatalf("nil diff not empty: %+v", nd) + } + if _, err := json.Marshal(d); err != nil { + t.Fatal(err) + } +} + +func TestDiffStatesAddedRemovedChanged(t *testing.T) { + a := techdocs(t) + b := Clone(a) + // change one, remove one, add one (with a region to exercise flattening) + b.Spec.States[0].Label = "Requested (new)" + b.Spec.States[0].Lifecycle.Number = 11 + b.Spec.States[0].Lifecycle.Replies = []string{"triage"} + removed := b.Spec.States[len(b.Spec.States)-1].ID + b.Spec.States = b.Spec.States[:len(b.Spec.States)-1] + b.Spec.States = append(b.Spec.States, State{ID: "parallel", Owner: OwnerHuman, Type: StateParallel, Regions: []State{{ID: "inner", Owner: OwnerHuman, Lifecycle: StateLifecycle{Confidence: ConfidenceInferred}}}}) + + d := Diff(a, b) + if d.Empty { + t.Fatal("expected changes") + } + if !reflect.DeepEqual(d.States.Added, []string{"inner", "parallel"}) { + t.Fatalf("added %v", d.States.Added) + } + if !reflect.DeepEqual(d.States.Removed, []string{removed}) { + t.Fatalf("removed %v", d.States.Removed) + } + if len(d.States.Changed) != 1 || d.States.Changed[0].Key != a.Spec.States[0].ID { + t.Fatalf("changed %+v", d.States.Changed) + } + fields := map[string]FieldChange{} + for _, f := range d.States.Changed[0].Fields { + fields[f.Field] = f + } + if fields["label"].To != "Requested (new)" || fields["number"] != (FieldChange{"number", "10", "11"}) || fields["replies"] != (FieldChange{"replies", "", "triage"}) { + t.Fatalf("fields %+v", fields) + } + if len(fields) != 3 { + t.Fatalf("unexpected field changes: %+v", fields) + } + if d.Summary != "+2 states, −1 state, 1 changed" { + t.Fatalf("summary %q", d.Summary) + } + // reverse direction swaps added/removed + r := Diff(b, a) + if !reflect.DeepEqual(r.States.Removed, []string{"inner", "parallel"}) || !reflect.DeepEqual(r.States.Added, []string{removed}) { + t.Fatalf("reverse %+v", r.States) + } +} + +func TestDiffTransitionsLabelsColumnsRulesMeta(t *testing.T) { + a := techdocs(t) + b := Clone(a) + b.Spec.Transitions[0].Note = "edited" + b.Spec.Transitions[0].GuardRef = "g1" + b.Spec.Transitions = b.Spec.Transitions[1:] + b.Spec.Transitions = append(b.Spec.Transitions, Transition{From: "approved", To: "withdrawn", On: "closed"}, Transition{From: "approved", To: "withdrawn", On: "rejected"}) + b.Spec.Labels.Entries = append(b.Spec.Labels.Entries, LabelEntry{Name: "stage/010-requested", State: "requested"}) + b.Spec.Columns[0].Label = "Inbox" + b.Spec.Columns = append(b.Spec.Columns, Column{ID: "extra", States: []string{"requested"}}) + b.Spec.Derivation.Rules = append(b.Spec.Derivation.Rules, Rule{State: "requested", When: []Predicate{{Fact: "open", Op: OpTrue}}}, Rule{ID: "named", State: "withdrawn"}) + b.Spec.Meta.Version = "2" + b.Spec.Meta.Provenance = ProvenanceLocal + + d := Diff(a, b) + removedKey := a.Spec.Transitions[0].From + ">" + a.Spec.Transitions[0].To + if !reflect.DeepEqual(d.Transitions.Removed, []string{removedKey}) { + t.Fatalf("transitions removed %v", d.Transitions.Removed) + } + if !reflect.DeepEqual(d.Transitions.Added, []string{"approved>withdrawn@closed", "approved>withdrawn@rejected"}) { + t.Fatalf("transitions added %v", d.Transitions.Added) + } + if d.Transitions.Len() != 3 { + t.Fatalf("transitions %+v", d.Transitions) + } + if !reflect.DeepEqual(d.Labels.Added, []string{"stage/010-requested"}) || d.Labels.Len() != 1 { + t.Fatalf("labels %+v", d.Labels) + } + if !reflect.DeepEqual(d.Columns.Added, []string{"extra"}) || len(d.Columns.Changed) != 1 || d.Columns.Changed[0].Fields[0] != (FieldChange{"label", a.Spec.Columns[0].Label, "Inbox"}) { + t.Fatalf("columns %+v", d.Columns) + } + wantRules := []string{"named", "rules[" + strconv.Itoa(len(a.Spec.Derivation.Rules)) + "]"} + if !reflect.DeepEqual(d.Rules.Added, wantRules) { + t.Fatalf("rules %v want %v", d.Rules.Added, wantRules) + } + meta := map[string]FieldChange{} + for _, f := range d.Meta { + meta[f.Field] = f + } + if meta["version"] != (FieldChange{"version", "1", "2"}) || meta["provenance"].To != string(ProvenanceLocal) || len(meta) != 2 { + t.Fatalf("meta %+v", d.Meta) + } + for _, want := range []string{"+1 column", "−1 transition", "+2 transitions", "+1 label", "+2 rules", "changed"} { + if !strings.Contains(d.Summary, want) { + t.Fatalf("summary %q lacks %q", d.Summary, want) + } + } + // a transition whose fields change is reported as changed + c := Clone(a) + c.Spec.Transitions[0].Note = "why" + cd := Diff(a, c) + if len(cd.Transitions.Changed) != 1 || cd.Transitions.Changed[0].Fields[0] != (FieldChange{"note", a.Spec.Transitions[0].Note, "why"}) { + t.Fatalf("transition change %+v", cd.Transitions) + } + if cd.Summary != "1 changed" { + t.Fatalf("summary %q", cd.Summary) + } +} + +func TestConfirmClearsInferredAndLocalises(t *testing.T) { + a := techdocs(t) + a.Spec.Meta.Provenance = ProvenanceIngestedUnreviewed + a.Spec.Meta.Source = SourceGitHubActions + a.Spec.States[0].Lifecycle.Confidence = ConfidenceInferred + a.Spec.States = append(a.Spec.States, State{ID: "par", Owner: OwnerHuman, Type: StateParallel, Regions: []State{{ID: "in", Owner: OwnerHuman, Lifecycle: StateLifecycle{Confidence: ConfidenceInferred}}}}) + a.Spec.Events = append(a.Spec.Events, Event{ID: "ev", Fact: Predicate{Fact: "open", Op: OpTrue}, Confidence: ConfidenceInferred}) + a.Spec.Gates = append(a.Spec.Gates, Gate{ID: "gt", ReleasedBy: "maintainer", Confidence: ConfidenceInferred}) + if Inferred(a) != 4 { + t.Fatalf("inferred %d", Inferred(a)) + } + before := a.Hash() + + c := Confirm(a, "andy") + if Inferred(c) != 0 { + t.Fatalf("confirmed model still has %d inferred", Inferred(c)) + } + if c.Spec.Meta.Provenance != ProvenanceLocal || c.Spec.Meta.Version != "" || c.Spec.Meta.Source != SourceGitHubActions { + t.Fatalf("meta %+v", c.Spec.Meta) + } + if c.Metadata.Annotations[AnnotationConfirmedBy] != "andy" { + t.Fatalf("annotations %v", c.Metadata.Annotations) + } + if c.Metadata.Name != a.Metadata.Name || len(c.Spec.States) != len(a.Spec.States) { + t.Fatal("confirm lost structure") + } + // original untouched + if a.Hash() != before || Inferred(a) != 4 || a.Spec.Meta.Provenance != ProvenanceIngestedUnreviewed || a.Metadata.Annotations != nil { + t.Fatal("Confirm mutated its input") + } + // no annotation without a user; nil in → nil out + if Confirm(a, "").Metadata.Annotations != nil || Confirm(nil, "x") != nil || Clone(nil) != nil || Inferred(nil) != 0 { + t.Fatal("edge cases") + } +} + +func TestProfileLabelDefs(t *testing.T) { + m := techdocs(t) + m.Spec.Labels = LabelSet{Prefix: "stage", Entries: []LabelEntry{ + {Name: "stage/010-requested", State: "requested"}, + {Name: "stage/020-analysing", Color: "123456", Description: "explicit", State: "analysing"}, + {Name: "", State: "ghost"}, + {Name: "orphan", State: "nope"}, + }} + p, _, err := Compile(m) + if err != nil { + t.Fatal(err) + } + got := p.LabelDefs("abcdef") + want := []LabelDef{ + {Name: "stage/010-requested", Color: "abcdef", Description: m.Spec.States[0].Label, State: "requested"}, + {Name: "stage/020-analysing", Color: "123456", Description: "explicit", State: "analysing"}, + {Name: "orphan", Color: "abcdef", State: "nope"}, + } + if !reflect.DeepEqual(got, want) { + t.Fatalf("got %+v\nwant %+v", got, want) + } + if (*Profile)(nil).LabelDefs("x") != nil { + t.Fatal("nil profile") + } + if n := len(techdocsProfile(t).LabelDefs("x")); n != 0 { + t.Fatalf("model without labels block yields %d defs", n) + } +} + +func techdocsProfile(t *testing.T) *Profile { + t.Helper() + p, _, err := Compile(techdocs(t)) + if err != nil { + t.Fatal(err) + } + return p +} diff --git a/src/pkg/workflowmodel/store/store.go b/src/pkg/workflowmodel/store/store.go index b81d46dba7..dfaf50a531 100644 --- a/src/pkg/workflowmodel/store/store.go +++ b/src/pkg/workflowmodel/store/store.go @@ -20,6 +20,7 @@ import ( "path/filepath" "regexp" "sort" + "strconv" "strings" "sync" "time" @@ -413,3 +414,33 @@ func writeAtomic(path string, b []byte) error { } return os.Rename(tmp, path) } + +// NextVersion returns the next free integer version of name: one more +// than the largest integer version saved so far, or "1" for a name with no +// integer versions. Non-integer versions (semver, tags) are ignored for +// the count but can never be returned, so the result is always unused. +func (s *Store) NextVersion(name string) (string, error) { + if !nameRe.MatchString(name) { + return "", fmt.Errorf("%w: %q", ErrBadName, name) + } + all, err := s.List() + if err != nil { + return "", err + } + max := 0 + taken := map[string]bool{} + for _, e := range all { + if e.Name != name { + continue + } + taken[e.Version] = true + if n, err := strconv.Atoi(e.Version); err == nil && n > max { + max = n + } + } + for v := max + 1; ; v++ { + if s := strconv.Itoa(v); !taken[s] { + return s, nil + } + } +} diff --git a/src/pkg/workflowmodel/store/store_test.go b/src/pkg/workflowmodel/store/store_test.go index 01d178341d..21b011da6b 100644 --- a/src/pkg/workflowmodel/store/store_test.go +++ b/src/pkg/workflowmodel/store/store_test.go @@ -257,3 +257,26 @@ func TestRoot(t *testing.T) { t.Fatal("env must win") } } + +func TestNextVersion(t *testing.T) { + s := Open(t.TempDir()) + m := techdocs(t) + if v, err := s.NextVersion(m.Metadata.Name); err != nil || v != "1" { + t.Fatalf("empty: %q %v", v, err) + } + if _, err := s.NextVersion("Bad Name"); !errors.Is(err, ErrBadName) { + t.Fatal(err) + } + for _, v := range []string{"1", "3", "2.0-rc1"} { + m.Spec.Meta.Version = v + if _, err := s.Save(m, "andy", t0); err != nil { + t.Fatal(err) + } + } + if v, err := s.NextVersion(m.Metadata.Name); err != nil || v != "4" { + t.Fatalf("after 1,3,2.0-rc1: %q %v", v, err) + } + if v, err := s.NextVersion(hivedefault.Name); err != nil || v != "2" { + t.Fatalf("builtin: %q %v", v, err) + } +}