@intentius/chant 0.124.26 → 0.124.28

package/src/workspace/ci-last-green.schema.json

@@ -64,10 +64,10 @@
         },
         "ref": {
           "type": "string",
-          "description": "The ref whose first-parent commits were walked: refs/remotes/origin/<branch> when the checkout has it, else refs/heads/<branch>."
+          "description": "The ref whose first-parent commits were walked: refs/remotes/origin/<branch> when the checkout has it, else refs/heads/<branch>, or the revision --from names (#4031)."
         },
         "commit": {
-          "description": "The newest green commit that is not revoked, or null when there is none.",
+          "description": "The newest green commit that is not revoked, or null when there is none. Only tags that count are read: with ci.green.signedSince set, a tag on a commit that is not a strict first-parent ancestor of it counts only with a valid statement signed by a runner key (#4031).",
           "oneOf": [
             {
               "type": "null"
@@ -103,6 +103,36 @@
               }
             }
           ]
+        },
+        "ignored": {
+          "type": "array",
+          "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. The tags on the commits walked, newest first and down to the one found, that do not count for want of a valid statement. Empty when ci.green.signedSince is not set.",
+          "items": {
+            "type": "object",
+            "required": [
+              "tag",
+              "status",
+              "reason"
+            ],
+            "properties": {
+              "tag": {
+                "type": "string",
+                "description": "ci/green/<sha> or ci/revoked/<sha>."
+              },
+              "status": {
+                "enum": [
+                  "unsigned",
+                  "invalid",
+                  "untrusted",
+                  "mismatch"
+                ],
+                "description": "unsigned: the annotation carries no statement. invalid: the statement is not a ci-tag statement, or names another signer than the key's. untrusted: no runner key .chant/trust.json lists at base signed it, or its principal holds no runner role. mismatch: it signs another commit, tag kind or branch, the annotation's record is not the one signed, or the tag points at another commit than its name gives."
+              },
+              "reason": {
+                "type": "string"
+              }
+            }
+          }
         }
       }
     },

package/src/workspace/ci-list.schema.json

@@ -0,0 +1,525 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/ci-list/v1/ci-list.schema.json",
+  "title": "chant ci list output",
+  "description": "What `chant ci list --json` prints (#4021, ws-103): the first-parent commits of the branch ci.green names, newest first, within ci.green.window or after --since, each with its state from the ci/green/<sha> and ci/revoked/<sha> tags and the result of each required phase. It reads local refs and tags and never fetches; with --forge it also reads check runs for the commits that have no ci tag. With the source chant runs (ci.green.source or --source runs, #4044) it reads the signed Op runs on the local chant/lifecycle for those commits instead, and refuses --forge. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version, so a later release may add more fields to each commit. `work` says whether the commit names its work item; it was added by #4029. The codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.124.28 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0, with or without commits.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "workspace",
+        "branch",
+        "ref",
+        "window",
+        "since",
+        "require",
+        "commits"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/ci-list/v1/ci-list.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "workspace": {
+          "type": "object",
+          "required": [
+            "name",
+            "root",
+            "file"
+          ],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "root": {
+              "type": "string",
+              "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself."
+            },
+            "file": {
+              "enum": [
+                "chant.workspace.json",
+                "chant.workspace.jsonc"
+              ]
+            }
+          }
+        },
+        "branch": {
+          "type": "string",
+          "description": "ci.green.branch."
+        },
+        "ref": {
+          "type": "string",
+          "description": "The ref whose first-parent commits were walked: refs/remotes/origin/<branch> when the checkout has it, else refs/heads/<branch>."
+        },
+        "window": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "ci.green.window, or null when --since replaced it."
+        },
+        "since": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The revision --since named; the commits listed come after it. Null when it was not given."
+        },
+        "require": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "ci.green.require: the phases a commit must pass, in order. Each commit's phases list them in the same order."
+        },
+        "commits": {
+          "type": "array",
+          "description": "Newest first.",
+          "items": {
+            "type": "object",
+            "required": [
+              "sha",
+              "committed",
+              "state",
+              "green",
+              "revoked",
+              "phases"
+            ],
+            "properties": {
+              "sha": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{40,64}$"
+              },
+              "committed": {
+                "type": "string",
+                "description": "The commit's committer time, ISO 8601, UTC."
+              },
+              "state": {
+                "enum": [
+                  "green",
+                  "revoked",
+                  "undecided"
+                ],
+                "description": "revoked when the commit has a revoked tag, else green when it has a green tag, else undecided."
+              },
+              "green": {
+                "description": "The commit's green tag, or null.",
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "tag",
+                      "tagged"
+                    ],
+                    "properties": {
+                      "tag": {
+                        "type": "string",
+                        "description": "ci/green/<sha>."
+                      },
+                      "tagged": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "description": "When the tag was made, ISO 8601, or null for a lightweight tag."
+                      },
+                      "signer": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. The runner principal whose statement the tag carries, or null when it counts unsigned: ci.green.signedSince is not set, or the commit is a strict first-parent ancestor of it."
+                      }
+                    }
+                  }
+                ]
+              },
+              "revoked": {
+                "description": "The commit's revoked tag, or null.",
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "tag",
+                      "tagged",
+                      "phase",
+                      "run"
+                    ],
+                    "properties": {
+                      "tag": {
+                        "type": "string",
+                        "description": "ci/revoked/<sha>."
+                      },
+                      "tagged": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "description": "When the tag was made, ISO 8601, or null for a lightweight tag."
+                      },
+                      "phase": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "description": "The phase the annotation names as failed, or null when the annotation can't be read."
+                      },
+                      "run": {
+                        "oneOf": [
+                          {
+                            "type": "null"
+                          },
+                          {
+                            "type": "object",
+                            "required": [
+                              "name",
+                              "id",
+                              "conclusion",
+                              "url"
+                            ],
+                            "properties": {
+                              "name": {
+                                "type": "string"
+                              },
+                              "id": {
+                                "type": [
+                                  "integer",
+                                  "null"
+                                ]
+                              },
+                              "conclusion": {
+                                "type": [
+                                  "string",
+                                  "null"
+                                ]
+                              },
+                              "url": {
+                                "type": [
+                                  "string",
+                                  "null"
+                                ]
+                              },
+                              "opRun": {
+                                "type": "object",
+                                "required": [
+                                  "id",
+                                  "env",
+                                  "signer"
+                                ],
+                                "properties": {
+                                  "id": {
+                                    "type": "string",
+                                    "description": "The Op run's id."
+                                  },
+                                  "env": {
+                                    "type": "string",
+                                    "description": "The env the run is recorded under."
+                                  },
+                                  "signer": {
+                                    "type": "string",
+                                    "description": "The runner principal whose statement the run carries."
+                                  }
+                                },
+                                "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the run is a chant Op run (ci.green.source runs): name is then the Op's name and id is null. Absent for a check run."
+                              }
+                            }
+                          }
+                        ],
+                        "description": "The run the annotation names as failed."
+                      },
+                      "signer": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. The runner principal whose statement the tag carries, or null when it counts unsigned: ci.green.signedSince is not set, or the commit is a strict first-parent ancestor of it."
+                      }
+                    }
+                  }
+                ]
+              },
+              "phases": {
+                "type": "array",
+                "description": "Each required phase, in `require` order.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "phase",
+                    "result",
+                    "runs"
+                  ],
+                  "properties": {
+                    "phase": {
+                      "type": "string"
+                    },
+                    "result": {
+                      "enum": [
+                        "pass",
+                        "fail",
+                        "pending",
+                        "unrecorded"
+                      ],
+                      "description": "pass and fail come from the tags (a green tag records the phases that passed, a revoked tag the one that failed) or, for an undecided commit, from the forge under --forge, or from the signed Op runs on the local chant/lifecycle when the source is chant runs (#4044). pending is such a read with runs still going or not yet reported. unrecorded means no tag holds the result and nothing was read."
+                    },
+                    "runs": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "name",
+                          "id",
+                          "conclusion",
+                          "url"
+                        ],
+                        "properties": {
+                          "name": {
+                            "type": "string"
+                          },
+                          "id": {
+                            "type": [
+                              "integer",
+                              "null"
+                            ]
+                          },
+                          "conclusion": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "url": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "opRun": {
+                            "type": "object",
+                            "required": [
+                              "id",
+                              "env",
+                              "signer"
+                            ],
+                            "properties": {
+                              "id": {
+                                "type": "string",
+                                "description": "The Op run's id."
+                              },
+                              "env": {
+                                "type": "string",
+                                "description": "The env the run is recorded under."
+                              },
+                              "signer": {
+                                "type": "string",
+                                "description": "The runner principal whose statement the run carries."
+                              }
+                            },
+                            "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the run is a chant Op run (ci.green.source runs): name is then the Op's name and id is null. Absent for a check run."
+                          }
+                        }
+                      },
+                      "description": "The check runs behind the result: those the green tag recorded, the failed run a revoked tag names, or those the forge returned. Empty when unrecorded."
+                    }
+                  }
+                }
+              },
+              "work": {
+                "description": "Whether the commit names the work item it belongs to (#4029), by the definition `workspace check --changes` uses: a Chant-Record trailer of a work kind the declaration names whose record exists, or a Chant-Lease trailer that resolves to a work item. The records are read at `ref`. A window match does not count. Null when the checkout is not in a workspace that declares a work kind, or the kinds can't be read. Added within contract version 1, and written by chant 0.124.28 and newer; a reader that finds no `work` is reading an older chant, and one that finds null has been told nothing. A commit that is unlinked or wrong is why its work item is unknown.",
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "state",
+                      "ids",
+                      "problems"
+                    ],
+                    "properties": {
+                      "state": {
+                        "enum": [
+                          "linked",
+                          "unlinked",
+                          "wrong",
+                          "merge"
+                        ],
+                        "description": "linked: a trailer names a work record that exists, or a lease that resolves to one (a lease is taken as linked when this checkout has no chant/lifecycle branch to read). unlinked: no Chant-Record or Chant-Lease trailer names anything. wrong: trailers name a work item but none of them is one that exists. merge: a merge commit, whose work is the commits it brings."
+                      },
+                      "ids": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        },
+                        "description": "The work records the trailers name, as <kind>:<id>. Empty unless state is linked."
+                      },
+                      "problems": {
+                        "type": "array",
+                        "description": "The trailers that do not link the commit. Empty unless state is wrong.",
+                        "items": {
+                          "type": "object",
+                          "required": [
+                            "trailer",
+                            "message"
+                          ],
+                          "properties": {
+                            "trailer": {
+                              "type": "string"
+                            },
+                            "message": {
+                              "type": "string"
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                ]
+              },
+              "ignored": {
+                "type": "array",
+                "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. The commit's ci tags that do not count for want of a valid statement signed by a runner key. A tag on any commit that is not a strict first-parent ancestor of ci.green.signedSince needs one; empty when signedSince is not set. state, green and revoked count only the tags that are not ignored.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "tag",
+                    "status",
+                    "reason"
+                  ],
+                  "properties": {
+                    "tag": {
+                      "type": "string",
+                      "description": "ci/green/<sha> or ci/revoked/<sha>."
+                    },
+                    "status": {
+                      "enum": [
+                        "unsigned",
+                        "invalid",
+                        "untrusted",
+                        "mismatch"
+                      ],
+                      "description": "unsigned: the annotation carries no statement. invalid: the statement is not a ci-tag statement, or names another signer than the key's. untrusted: no runner key .chant/trust.json lists at base signed it, or its principal holds no runner role. mismatch: it signs another commit, tag kind or branch, the annotation's record is not the one signed, or the tag points at another commit than its name gives."
+                    },
+                    "reason": {
+                      "type": "string"
+                    }
+                  }
+                }
+              },
+              "ignoredRuns": {
+                "type": "array",
+                "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the source is chant runs (ci.green.source or --source runs): the Op runs on the commit that do not count for want of a valid statement signed by a runner key whose principal holds the runner role. They neither green nor revoke the commit.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "run",
+                    "op",
+                    "env",
+                    "status",
+                    "reason"
+                  ],
+                  "properties": {
+                    "run": {
+                      "type": "string",
+                      "description": "The Op run's id."
+                    },
+                    "op": {
+                      "type": "string"
+                    },
+                    "env": {
+                      "type": "string"
+                    },
+                    "status": {
+                      "enum": [
+                        "unsigned",
+                        "invalid",
+                        "untrusted",
+                        "mismatch"
+                      ],
+                      "description": "unsigned: the record carries no statement. invalid: the statement is not an op-run statement, or names another signer than the key's. untrusted: no runner key .chant/trust.json lists at base signed it, or its principal holds no runner role. mismatch: it signs another run, commit or record than the ledger holds."
+                    },
+                    "reason": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was read. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/ci-list/v1/ci-list.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown",
+                "ci-green-undeclared",
+                "ci-branch-unknown"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}