@intentius/sql-yodeler 0.1.0 → 0.2.0

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"
+        ]
+      }
+    }
+  }
+}

package/schemas/lint.schema.json

@@ -0,0 +1,290 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/lint.schema.json",
+  "title": "yodel lint --json",
+  "description": "Version 1. The findings, the silences each migration holds, and with --replay the replay check's result. yodel lint --rules --json prints lint-rules.schema.json instead. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "dialect",
+    "migrations",
+    "errors",
+    "warnings",
+    "silenced",
+    "findings",
+    "silences"
+  ],
+  "properties": {
+    "status": {
+      "description": "failed when a finding at level error is not silenced: the command exits 3.",
+      "enum": [
+        "passed",
+        "failed"
+      ]
+    },
+    "environment": {
+      "description": "With --env: the environment whose history the migrations were compared with.",
+      "type": "string"
+    },
+    "dialect": {
+      "oneOf": [
+        {
+          "$ref": "common.schema.json#/$defs/dialect"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "migrations": {
+      "description": "Every migration read, sorted by id.",
+      "$ref": "common.schema.json#/$defs/stringList"
+    },
+    "errors": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "warnings": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "silenced": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "rule",
+          "level",
+          "message"
+        ],
+        "properties": {
+          "rule": {
+            "type": "string"
+          },
+          "level": {
+            "enum": [
+              "error",
+              "warning"
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "migration": {
+            "type": "string"
+          },
+          "step": {
+            "type": "integer"
+          },
+          "object": {
+            "type": "string"
+          },
+          "line": {
+            "type": "integer"
+          },
+          "silenced": {
+            "description": "A -- yodel:allow line silenced it: the reason given. A silenced finding fails nothing.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "silences": {
+      "description": "The silences each migration's migration.sql holds, by migration id.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "step",
+            "rule",
+            "reason",
+            "line"
+          ],
+          "properties": {
+            "step": {
+              "type": "integer"
+            },
+            "rule": {
+              "type": "string"
+            },
+            "reason": {
+              "type": "string"
+            },
+            "line": {
+              "type": "integer"
+            }
+          }
+        }
+      }
+    },
+    "replay": {
+      "$ref": "#/$defs/replay"
+    }
+  },
+  "$defs": {
+    "replayed": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "statements",
+        "ran",
+        "skipped"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "statements": {
+          "type": "integer"
+        },
+        "ran": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "skipped": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        }
+      }
+    },
+    "replay": {
+      "description": "With --replay: the history replayed into an empty database, migration by migration, against each one's recorded schema.",
+      "type": "object",
+      "required": [
+        "dialect",
+        "where",
+        "scope",
+        "reset",
+        "kept",
+        "matched",
+        "total",
+        "outcome",
+        "ok"
+      ],
+      "unevaluatedProperties": false,
+      "properties": {
+        "dialect": {
+          "$ref": "common.schema.json#/$defs/dialect"
+        },
+        "where": {
+          "type": "string"
+        },
+        "scope": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "reset": {
+          "type": "boolean"
+        },
+        "kept": {
+          "type": "boolean"
+        },
+        "matched": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/replayed"
+          }
+        },
+        "total": {
+          "type": "integer"
+        },
+        "outcome": {
+          "enum": [
+            "matches",
+            "differs",
+            "failed",
+            "unreplayable"
+          ]
+        },
+        "ok": {
+          "type": "boolean"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "oneOf": [
+        {
+          "properties": {
+            "outcome": {
+              "const": "matches"
+            }
+          },
+          "type": "object"
+        },
+        {
+          "required": [
+            "migration",
+            "changes"
+          ],
+          "properties": {
+            "outcome": {
+              "const": "differs"
+            },
+            "migration": {
+              "$ref": "#/$defs/replayed"
+            },
+            "changes": {
+              "type": "array",
+              "items": {
+                "$ref": "common.schema.json#/$defs/change"
+              }
+            }
+          },
+          "type": "object"
+        },
+        {
+          "required": [
+            "migration",
+            "step",
+            "error"
+          ],
+          "properties": {
+            "outcome": {
+              "const": "failed"
+            },
+            "migration": {
+              "type": "string"
+            },
+            "step": {
+              "type": "integer"
+            },
+            "error": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        {
+          "required": [
+            "migration",
+            "step",
+            "reason"
+          ],
+          "properties": {
+            "outcome": {
+              "const": "unreplayable"
+            },
+            "migration": {
+              "type": "string"
+            },
+            "step": {
+              "type": "integer"
+            },
+            "reason": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        }
+      ]
+    }
+  }
+}