@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/schemas/apply.schema.json

@@ -0,0 +1,269 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/apply.schema.json",
+  "title": "yodel apply <env> --json",
+  "description": "Version 1. On a project with migrations, the status (status.schema.json) with mode \"versioned\" and what apply did; with --execute (the migrations Op's Apply step), what the step applied; on a project without migrations, the declarative outcome with chant's plan. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/versioned"
+    },
+    {
+      "$ref": "#/$defs/execute"
+    },
+    {
+      "$ref": "#/$defs/declarative"
+    }
+  ],
+  "$defs": {
+    "lock": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "where"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "keeper",
+            "local",
+            "advisory"
+          ]
+        },
+        "where": {
+          "type": "string"
+        },
+        "notice": {
+          "type": "string"
+        }
+      }
+    },
+    "versioned": {
+      "type": "object",
+      "$ref": "status.schema.json#/$defs/report",
+      "required": [
+        "mode",
+        "status"
+      ],
+      "unevaluatedProperties": false,
+      "properties": {
+        "mode": {
+          "const": "versioned"
+        },
+        "status": {
+          "description": "planned (--plan, something pending), unchanged, refused, denied (a policy rule denies the plan, with no override), gated (waiting at the Op's gate for a person's approval), failed, applied.",
+          "enum": [
+            "planned",
+            "unchanged",
+            "refused",
+            "denied",
+            "gated",
+            "failed",
+            "applied"
+          ]
+        },
+        "preChecks": {
+          "description": "The first pending migration's checks, when one failed before the gate.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "migration",
+            "checks"
+          ],
+          "properties": {
+            "migration": {
+              "type": "string"
+            },
+            "checks": {
+              "type": "array",
+              "items": {
+                "$ref": "common.schema.json#/$defs/checkOutcome"
+              }
+            }
+          }
+        },
+        "policy": {
+          "description": "denied: each policy rule's outcome.",
+          "$ref": "common.schema.json#/$defs/policy"
+        },
+        "op": {
+          "type": "string"
+        },
+        "gate": {
+          "type": "string"
+        },
+        "approve": {
+          "description": "gated: the command a person runs to approve. An agent prints it and never runs it.",
+          "type": "string"
+        },
+        "gatePlanDigest": {
+          "type": "string"
+        },
+        "moved": {
+          "description": "gated: the gate's newest approval does not hold, and what moved since it.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "approved",
+            "by",
+            "at",
+            "confirmed",
+            "changes"
+          ],
+          "properties": {
+            "approved": {
+              "type": "string"
+            },
+            "by": {
+              "type": "string"
+            },
+            "at": {
+              "type": "string"
+            },
+            "confirmed": {
+              "type": "boolean"
+            },
+            "changes": {
+              "$ref": "plan.schema.json#/$defs/moved"
+            },
+            "askedAgain": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "at"
+              ],
+              "properties": {
+                "at": {
+                  "type": "string"
+                },
+                "digest": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "exitCode": {
+          "description": "failed: yodel apply's exit code, the Apply step's own when it had one.",
+          "type": "integer"
+        },
+        "chantExitCode": {
+          "description": "failed: chant run's exit code.",
+          "type": "integer"
+        },
+        "appliedNow": {
+          "description": "applied: the migrations this run applied.",
+          "$ref": "common.schema.json#/$defs/stringList"
+        }
+      }
+    },
+    "execute": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "environment",
+        "status",
+        "planDigest",
+        "applied",
+        "skipped",
+        "lock"
+      ],
+      "properties": {
+        "environment": {
+          "type": "string"
+        },
+        "status": {
+          "const": "applied"
+        },
+        "planDigest": {
+          "description": "The digest the gate approved.",
+          "type": "string"
+        },
+        "applied": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "skipped": {
+          "description": "Statements not sent because an earlier run had already succeeded with them.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "statement"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "statement": {
+                "type": "integer"
+              }
+            }
+          }
+        },
+        "lock": {
+          "$ref": "#/$defs/lock"
+        }
+      }
+    },
+    "declarative": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "environment",
+        "dialect",
+        "op",
+        "status",
+        "plan"
+      ],
+      "properties": {
+        "environment": {
+          "type": "string"
+        },
+        "dialect": {
+          "$ref": "common.schema.json#/$defs/dialect"
+        },
+        "server": {
+          "$ref": "common.schema.json#/$defs/server"
+        },
+        "op": {
+          "description": "The ApplyOp.",
+          "type": "string"
+        },
+        "status": {
+          "enum": [
+            "refused",
+            "unchanged",
+            "gated",
+            "failed",
+            "incomplete",
+            "applied"
+          ]
+        },
+        "gate": {
+          "type": "string"
+        },
+        "approve": {
+          "description": "gated: the command a person runs to approve. An agent prints it and never runs it.",
+          "type": "string"
+        },
+        "planDigest": {
+          "type": "string"
+        },
+        "exitCode": {
+          "description": "failed: chant run's exit code.",
+          "type": "integer"
+        },
+        "plan": {
+          "description": "The plan before the run.",
+          "$ref": "plan.schema.json#/$defs/declarative"
+        },
+        "remaining": {
+          "description": "incomplete: the plan after the Op completed.",
+          "$ref": "plan.schema.json#/$defs/declarative"
+        }
+      }
+    }
+  }
+}

package/schemas/common.schema.json

@@ -0,0 +1,213 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/common.schema.json",
+  "title": "Definitions the yodel --json schemas share",
+  "description": "Version 1. Shared by the other schemas in this directory; no command prints this document on its own.",
+  "$defs": {
+    "dialect": {
+      "enum": [
+        "clickhouse",
+        "postgres"
+      ]
+    },
+    "server": {
+      "description": "The server read from: its dialect, its address (host:port on ClickHouse, host:port/database on Postgres) and its version, when it answered.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "dialect",
+        "address"
+      ],
+      "properties": {
+        "dialect": {
+          "$ref": "#/$defs/dialect"
+        },
+        "address": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "refusal": {
+      "description": "Why yodel apply would refuse, and the exit code it would refuse with.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "exitCode",
+        "message"
+      ],
+      "properties": {
+        "exitCode": {
+          "type": "integer"
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "change": {
+      "description": "One classified change, as chant's sql lexicon reports it. chant owns this object: fields beyond the required ones may appear.",
+      "type": "object",
+      "required": [
+        "object",
+        "field",
+        "rule",
+        "class"
+      ],
+      "properties": {
+        "object": {
+          "type": "string"
+        },
+        "field": {
+          "type": "string"
+        },
+        "before": {
+          "type": "string"
+        },
+        "after": {
+          "type": "string"
+        },
+        "rule": {
+          "type": "string"
+        },
+        "class": {
+          "type": "string"
+        },
+        "destructive": {
+          "type": "boolean"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    },
+    "check": {
+      "description": "A pre-migration check from migration.json.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "sql"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "sql": {
+          "type": "string"
+        },
+        "expect": {
+          "oneOf": [
+            {
+              "enum": [
+                "empty",
+                "true"
+              ]
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "min": {
+                  "type": "number"
+                },
+                "max": {
+                  "type": "number"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "checkOutcome": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "passed",
+        "detail"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "passed": {
+          "type": "boolean"
+        },
+        "detail": {
+          "type": "string"
+        }
+      }
+    },
+    "stringList": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "policy": {
+      "description": "The outcome of each rule of yodel.config.ts policy.rules over the plan.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "outcome",
+          "reasons"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "outcome": {
+            "description": "denied stands; overridden was denied, and an override counts.",
+            "enum": [
+              "allowed",
+              "denied",
+              "overridden"
+            ]
+          },
+          "reasons": {
+            "description": "Why it denies the plan, one line each.",
+            "$ref": "#/$defs/stringList"
+          },
+          "override": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "rule",
+              "by",
+              "at",
+              "reason",
+              "digest"
+            ],
+            "properties": {
+              "rule": {
+                "type": "string"
+              },
+              "by": {
+                "type": "string"
+              },
+              "at": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              },
+              "digest": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/drift.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/drift.schema.json",
+  "title": "yodel drift <env> --json",
+  "description": "Version 1. The declared objects changed out of band (changed) or gone (missing), and those chant could not read (unobserved: not drift, and not clean). Objects the project does not declare are never reported. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["environment", "dialect", "changed", "missing", "unobserved", "drifted"],
+  "properties": {
+    "environment": { "type": "string" },
+    "dialect": { "$ref": "common.schema.json#/$defs/dialect" },
+    "server": { "$ref": "common.schema.json#/$defs/server" },
+    "changed": {
+      "description": "chant's deep drift for each changed object: its name, kind and the properties that differ, declared against live. chant owns this object: fields beyond the required ones may appear.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["changes"],
+        "properties": { "changes": { "type": "array", "items": { "type": "object" } } }
+      }
+    },
+    "missing": { "$ref": "common.schema.json#/$defs/stringList" },
+    "unobserved": {
+      "description": "Declared objects chant could not read, each with its name and why.",
+      "type": "array",
+      "items": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" } } }
+    },
+    "lockWait": { "description": "Postgres: a read gave up at the lock timeout, and what it waited on.", "type": "string" },
+    "columns": {
+      "description": "Each changed table's declared column names, by position.",
+      "type": "object",
+      "additionalProperties": { "$ref": "common.schema.json#/$defs/stringList" }
+    },
+    "drifted": { "description": "A declared object changed or is gone: the command exits 2.", "type": "boolean" }
+  }
+}

package/schemas/init.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/init.schema.json",
+  "title": "yodel init --from <env> --json",
+  "description": "Version 1. What adopting a live database wrote: the declarations, the baseline migration, and the history row that records it applied. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["environment", "dialect", "status", "objects", "schemaFiles", "migration", "recorded", "warnings"],
+  "properties": {
+    "environment": { "type": "string" },
+    "dialect": { "$ref": "common.schema.json#/$defs/dialect" },
+    "status": { "const": "adopted" },
+    "objects": { "description": "The objects read, as <kind> <name>.", "$ref": "common.schema.json#/$defs/stringList" },
+    "schemaFiles": { "description": "The declaration files written, relative to the project.", "$ref": "common.schema.json#/$defs/stringList" },
+    "migration": {
+      "description": "The baseline migration.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "id", "checksum", "statements"],
+      "properties": { "path": { "type": "string" }, "id": { "type": "string" }, "checksum": { "type": "string" }, "statements": { "type": "integer" } }
+    },
+    "recorded": {
+      "description": "The baseline's history row.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["history", "seq", "note", "appliedBy"],
+      "properties": { "history": { "type": "string" }, "seq": { "type": "integer" }, "note": { "type": "string" }, "appliedBy": { "type": "string" } }
+    },
+    "warnings": { "$ref": "common.schema.json#/$defs/stringList" }
+  }
+}

package/schemas/lint-rules.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/lint-rules.schema.json",
+  "title": "yodel lint --rules --json",
+  "description": "Version 1. Every lint rule, with the level yodel.config.ts sets for it in this project. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "id",
+      "summary",
+      "level",
+      "silenceable",
+      "configurable",
+      "configured"
+    ],
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "summary": {
+        "type": "string"
+      },
+      "level": {
+        "description": "The rule's default level.",
+        "enum": [
+          "error",
+          "warning"
+        ]
+      },
+      "silenceable": {
+        "description": "A -- yodel:allow <id> <reason> line can silence it for one statement.",
+        "type": "boolean"
+      },
+      "configurable": {
+        "description": "yodel.config.ts lint.rules may change its level.",
+        "type": "boolean"
+      },
+      "dialect": {
+        "description": "The dialect it applies to; both when absent.",
+        "$ref": "common.schema.json#/$defs/dialect"
+      },
+      "configured": {
+        "description": "The level in this project.",
+        "enum": [
+          "error",
+          "warning",
+          "off"
+        ]
+      }
+    }
+  }
+}