@intentius/sql-yodeler 0.0.0-stage → 0.2.0

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

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