@intentius/sql-yodeler 0.1.0 → 0.3.0

package/schemas/drift.schema.json

@@ -0,0 +1,61 @@
+{
+  "$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" }
+    },
+    "against": {
+      "description": "What the server was compared with: src, the project's declarations; or history, the schema the newest applied migration records (migration null when none is applied yet).",
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["source"], "properties": { "source": { "const": "src" } } },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["source", "migration"],
+          "properties": { "source": { "const": "history" }, "migration": { "type": ["string", "null"] } }
+        }
+      ]
+    },
+    "drifted": { "description": "A declared object changed or is gone: the command exits 2.", "type": "boolean" },
+    "fingerprint": { "description": "A hash of the environment and what drifted: the same for the same drift, run after run.", "type": "string" },
+    "issue": {
+      "description": "--issue: what yodel did with the environment's tracking issue, and the issue when there is one.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action"],
+      "properties": {
+        "action": { "enum": ["opened", "updated", "unchanged", "closed", "left", "none"] },
+        "number": { "type": "integer" },
+        "url": { "type": "string" }
+      }
+    },
+    "issueError": { "description": "--issue: the tracking issue could not be written, and why.", "type": "string" }
+  }
+}

package/schemas/event.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/event.schema.json",
+  "title": "a yodel webhook event",
+  "description": "Version 1. The body yodel apply, yodel plan and yodel drift post to the webhook yodel.config.ts notify names, signed with HMAC-SHA256 over '<x-yodel-timestamp>.<body>' in the x-yodel-signature header. Within a version, fields are only added; a receiver ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "id", "event", "at", "environment", "command", "status", "summary", "migrations"],
+  "properties": {
+    "version": { "const": 1 },
+    "id": { "type": "string", "description": "Unique per event; also the x-yodel-delivery header." },
+    "event": { "enum": ["waiting", "refused", "failed", "drift"] },
+    "at": { "type": "string", "format": "date-time" },
+    "environment": { "type": "string" },
+    "command": { "enum": ["apply", "plan", "drift"] },
+    "status": { "type": "string", "description": "The command's own word for the outcome: gated, refused, denied, failed, incomplete, drifted." },
+    "summary": { "type": "string" },
+    "migrations": { "type": "array", "items": { "type": "string" }, "description": "The pending migrations, for apply and plan." },
+    "digest": { "type": "string", "description": "The plan digest the run computed." },
+    "approve": { "type": "string", "description": "On waiting: the command that approves the plan." },
+    "reason": { "type": "string" },
+    "drift": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["changed", "missing"],
+      "properties": {
+        "changed": { "type": "array", "items": { "type": "string" } },
+        "missing": { "type": "array", "items": { "type": "string" } },
+        "fingerprint": { "type": "string", "description": "The same drift has the same fingerprint run after run, so a receiver can tell a repeat from new drift." }
+      }
+    },
+    "runUrl": { "type": "string" },
+    "repository": { "type": "string" },
+    "commit": { "type": "string" }
+  }
+}

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,294 @@
+{
+  "$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"
+        },
+        "checkpoint": {
+          "description": "A checkpoint, replayed on its own into an empty database after the chain.",
+          "const": true
+        }
+      }
+    },
+    "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"
+        }
+      ]
+    }
+  }
+}

package/schemas/mcp.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/mcp.schema.json",
+  "title": "A yodel mcp tool result",
+  "description": "Version 1. Every tool of yodel mcp returns this envelope, as the call's structuredContent and as its text. results follows the schema resultsSchema names: the command's own (status, plan, lint, drift) or a definition here (history, explain). Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "tool", "command", "exit", "results", "resultsSchema"],
+  "properties": {
+    "schema": { "description": "The envelope's version.", "const": 1 },
+    "tool": { "enum": ["status", "plan", "lint", "drift", "history", "explain"] },
+    "command": { "description": "The yodel command line the tool ran.", "type": "string" },
+    "exit": { "description": "The command's exit code, the same as on a terminal (yodel --help lists them).", "type": "integer" },
+    "results": { "description": "What the command printed with --json; null when it printed nothing (it failed: see error)." },
+    "resultsSchema": { "description": "The $id of the schema results follows.", "type": "string" },
+    "error": { "description": "What the command wrote to stderr: why it failed when results is null, else notices.", "type": "string" },
+    "forPerson": {
+      "description": "Steps that belong to a person, each with the command the person runs. An agent shows them and never runs them.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["action", "command"],
+        "properties": { "action": { "type": "string" }, "command": { "type": "string" } }
+      }
+    }
+  },
+  "$defs": {
+    "history": {
+      "description": "The history tool: the migrations the environment's history records applied, from yodel status.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["environment", "history", "applied"],
+      "properties": {
+        "environment": { "type": "string" },
+        "server": { "$ref": "common.schema.json#/$defs/server" },
+        "history": { "$ref": "status.schema.json#/$defs/report/properties/history" },
+        "applied": { "$ref": "status.schema.json#/$defs/report/properties/applied" }
+      }
+    },
+    "explain": {
+      "description": "The explain tool: a lint rule, or an exit code.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["topic", "kind", "rule", "docs"],
+          "properties": {
+            "topic": { "type": "string" },
+            "kind": { "const": "lint-rule" },
+            "rule": { "$ref": "lint-rules.schema.json#/items" },
+            "docs": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["topic", "kind", "code", "meaning", "docs"],
+          "properties": {
+            "topic": { "type": "string" },
+            "kind": { "const": "exit-code" },
+            "code": { "type": "integer" },
+            "meaning": { "type": "string" },
+            "docs": { "type": "string" }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/new.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/new.schema.json",
+  "title": "yodel new <name> --json",
+  "description": "Version 1. The migration written (written true), or why none was: a backfill template to fill in, a --replace that kept the migration, or no change from the newest migration's recorded schema. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "oneOf": [{ "$ref": "#/$defs/written" }, { "$ref": "#/$defs/template" }, { "$ref": "#/$defs/kept" }, { "$ref": "#/$defs/unchanged" }],
+  "$defs": {
+    "written": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["written", "id", "path", "parent", "checksum", "dialect", "statements", "ops", "manual", "hints", "checks"],
+      "properties": {
+        "written": { "const": true },
+        "id": { "type": "string" },
+        "path": { "type": "string" },
+        "parent": { "type": ["string", "null"] },
+        "checksum": { "type": "string" },
+        "dialect": { "$ref": "common.schema.json#/$defs/dialect" },
+        "statements": { "type": "integer", "minimum": 0 },
+        "ops": {
+          "description": "The Op steps written, which yodel apply runs or refuses.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["op", "object", "name", "rules"],
+            "properties": { "op": { "type": "string" }, "object": { "type": "string" }, "name": { "type": "string" }, "rules": { "$ref": "common.schema.json#/$defs/stringList" } }
+          }
+        },
+        "manual": {
+          "description": "The manual steps written: yodel apply refuses them.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["object", "name", "rules", "detail"],
+            "properties": { "object": { "type": "string" }, "name": { "type": "string" }, "rules": { "$ref": "common.schema.json#/$defs/stringList" }, "detail": { "type": "string" } }
+          }
+        },
+        "hints": { "$ref": "common.schema.json#/$defs/stringList" },
+        "checks": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/check" } }
+      }
+    },
+    "template": {
+      "description": "--backfill named a file that is not there: the template was written to it, and no migration.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["written", "template"],
+      "properties": { "written": { "const": false }, "template": { "type": "string" } }
+    },
+    "kept": {
+      "description": "--replace: the replacement would be the same, so the migration was kept.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["written", "replaced", "kept"],
+      "properties": { "written": { "const": false }, "replaced": { "type": "null" }, "kept": { "type": "string" } }
+    },
+    "unchanged": {
+      "description": "The declared schema matches the newest migration's recorded schema.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["written", "parent", "dialect", "hints"],
+      "properties": {
+        "written": { "const": false },
+        "parent": { "type": ["string", "null"] },
+        "dialect": { "$ref": "common.schema.json#/$defs/dialect" },
+        "hints": { "$ref": "common.schema.json#/$defs/stringList" }
+      }
+    }
+  }
+}