@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/declaration.schema.json

@@ -0,0 +1,434 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/declaration/v1/chant.workspace.schema.json",
+  "title": "chant.workspace.json",
+  "description": "A workspace declaration, schema 1 (#2524 D1, D2; ws-051). Only this file makes a directory a workspace. It may also be named chant.workspace.jsonc, which allows comments and trailing commas; having both is an error. Unknown fields are refused, except fields whose names start with x-. A field added later within schema 1 is optional, and a declaration that uses one sets minReader to the first chant that knows it, so an older chant says so instead of misreading the file. Uniqueness of names and the placement rules are checked in code, since JSON Schema cannot say them.",
+  "type": "object",
+  "required": [
+    "name",
+    "schema",
+    "members"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "An editor hint. chant ignores it."
+    },
+    "$comment": {
+      "type": "string",
+      "description": "A note for people. chant ignores it."
+    },
+    "name": {
+      "$ref": "#/$defs/name",
+      "description": "The workspace's name. With a git revision it identifies the workspace to readers (#2524 D15)."
+    },
+    "schema": {
+      "const": 1,
+      "description": "The declaration format version."
+    },
+    "minReader": {
+      "$ref": "#/$defs/version",
+      "description": "The oldest chant that may read this declaration. An older chant refuses it with reader-too-old."
+    },
+    "members": {
+      "type": "array",
+      "description": "Members and example groups, in the order readers list them.",
+      "items": {
+        "$ref": "#/$defs/entry"
+      }
+    },
+    "pins": {
+      "type": "array",
+      "description": "The toolchain and plugins that read this workspace, pinned (#2524 D3, threat model). Member kinds come only from pinned packages, read as data from their ./workspace-kinds subpath (#2535).",
+      "items": {
+        "$ref": "#/$defs/pin"
+      }
+    },
+    "checks": {
+      "type": "object",
+      "description": "Severity for the declaration checks that allow it, keyed by WSP id (#2535, ws-028): error, warning, info or off. chant workspace check refuses an id it does not know, and one whose severity is fixed.",
+      "propertyNames": {
+        "pattern": "^WSP[0-9]{3}$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/severity"
+      }
+    }
+  },
+  "patternProperties": {
+    "^x-": true
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
+      "description": "Lowercase letters, digits and hyphens, starting with a letter or digit, at most 40 characters. _workspace and _members are reserved; the pattern already rules them out."
+    },
+    "kindName": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,39}$"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?$"
+    },
+    "dir": {
+      "type": "string",
+      "description": "A directory relative to the workspace root, with / separators: \".\" for the root itself, otherwise no leading /, no . or .. segments and no trailing /.",
+      "pattern": "^(\\.|(?!\\.\\.?(/|$))[^/\\\\]+(/(?!\\.\\.?(/|$))[^/\\\\]+)*)$"
+    },
+    "glob": {
+      "type": "string",
+      "description": "A glob over directories, relative to the workspace root: * and ? within one segment, ** across segments, [...] classes. No leading /, no . or .. segments.",
+      "pattern": "^(?!\\.\\.?(/|$))[^/\\\\]+(/(?!\\.\\.?(/|$))[^/\\\\]+)*$"
+    },
+    "severity": {
+      "enum": [
+        "error",
+        "warning",
+        "info",
+        "off"
+      ]
+    },
+    "suppress": {
+      "type": "array",
+      "description": "Declaration checks suppressed for this entry (#2535). Each names a WSP id and says why. A suppressed finding is still reported, as suppressed, and never fails check.",
+      "items": {
+        "type": "object",
+        "required": [
+          "check",
+          "because"
+        ],
+        "properties": {
+          "check": {
+            "type": "string",
+            "pattern": "^WSP[0-9]{3}$"
+          },
+          "because": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "patternProperties": {
+          "^x-": true
+        },
+        "additionalProperties": false
+      }
+    },
+    "outputName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "pattern": "^[^\\u0000-\\u001f]+$",
+      "description": "An output's name, compared exactly."
+    },
+    "link": {
+      "type": "object",
+      "description": "A member link: this member reads output of member (#2539).",
+      "required": [
+        "member",
+        "output"
+      ],
+      "properties": {
+        "member": {
+          "$ref": "#/$defs/name",
+          "description": "The producer: another member of this workspace."
+        },
+        "output": {
+          "$ref": "#/$defs/outputName",
+          "description": "The producer's output, matched exactly. It must be one the producer's kind exposes."
+        },
+        "kind": {
+          "$ref": "#/$defs/kindName",
+          "description": "The link kind. output, the default, is the only one so far: the consumer reads the named output."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "entry": {
+      "description": "A member, or an example group when kind is examples (ws-051).",
+      "type": "object",
+      "required": [
+        "kind"
+      ],
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/kindName"
+        }
+      },
+      "if": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "const": "examples"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "$ref": "#/$defs/group"
+      },
+      "else": {
+        "$ref": "#/$defs/member"
+      }
+    },
+    "member": {
+      "type": "object",
+      "description": "A member (#2524 D2). Its directory leaves the root project, and it gets its own build, lint and ledger.",
+      "required": [
+        "name",
+        "dir",
+        "kind"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/name",
+          "description": "Frozen once the member deploys; a rename is an alias record."
+        },
+        "dir": {
+          "$ref": "#/$defs/dir"
+        },
+        "kind": {
+          "$ref": "#/$defs/kindName",
+          "description": "How to read the member: chant, workspace, other, or a kind a pinned plugin supplies (#2535)."
+        },
+        "roles": {
+          "type": "array",
+          "description": "Roles the member plays. A role may point at a path inside the member.",
+          "items": {
+            "oneOf": [
+              {
+                "$ref": "#/$defs/kindName"
+              },
+              {
+                "type": "object",
+                "required": [
+                  "name"
+                ],
+                "properties": {
+                  "name": {
+                    "$ref": "#/$defs/kindName"
+                  },
+                  "path": {
+                    "$ref": "#/$defs/dir",
+                    "description": "Relative to the member's directory."
+                  }
+                },
+                "patternProperties": {
+                  "^x-": true
+                },
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "generated": {
+          "type": "array",
+          "description": "Files in the member's directory that a command writes (#2524 D14, #2541). chant workspace check fails when one differs from what its generator writes, unless the entry is marked handWritten with a reason. The lineage lock classes the same files as generated. skills/*/SKILL.md, which chant update writes, is listed implicitly for a chant member.",
+          "items": {
+            "$ref": "#/$defs/generatedFile"
+          }
+        },
+        "outputs": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "The outputs this member exposes as link targets (#2539), for a member whose kind takes them from the entry: other, or a kind a pinned package supplies. A chant member's outputs are read from its source, and a nested workspace exposes none.",
+          "items": {
+            "$ref": "#/$defs/outputName"
+          }
+        },
+        "links": {
+          "type": "array",
+          "description": "Member links (#2524 D6, #2539): the outputs of other members this member reads. A link is stated once, here on the consumer, and matched exactly against the producer's outputs. chant workspace check resolves it in source.",
+          "items": {
+            "$ref": "#/$defs/link"
+          }
+        },
+        "upstream": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where an embedded member's files come from. Versions live in the lock."
+        },
+        "because": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Why the member is there. Required for kind other."
+        },
+        "suppress": {
+          "$ref": "#/$defs/suppress"
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false,
+      "if": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "const": "other"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "because": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "because"
+        ]
+      }
+    },
+    "group": {
+      "type": "object",
+      "description": "An example group (ws-051): every directory the glob matches that holds a chant project is built and linted. A group has no ledger, releases or links, and its matches are never members. A match may sit inside a member's directory; that member leaves it to the group.",
+      "required": [
+        "name",
+        "kind",
+        "glob"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/name"
+        },
+        "kind": {
+          "const": "examples"
+        },
+        "glob": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/glob"
+            },
+            {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/glob"
+              }
+            }
+          ]
+        },
+        "suppress": {
+          "$ref": "#/$defs/suppress"
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "path": {
+      "type": "string",
+      "description": "A file or directory path with / separators: no leading /, no . or .. segments and no trailing /.",
+      "pattern": "^(?!\\.\\.?(/|$))[^/\\\\]+(/(?!\\.\\.?(/|$))[^/\\\\]+)*$"
+    },
+    "generatedFile": {
+      "type": "object",
+      "description": "One generated file of a member (#2524 D14, #2541).",
+      "required": [
+        "path",
+        "generator"
+      ],
+      "properties": {
+        "path": {
+          "$ref": "#/$defs/path",
+          "description": "The file, relative to the member's directory."
+        },
+        "generator": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The command line that writes the file, run in the member's directory with the member's own node_modules/.bin first on PATH, such as chant build ci --lexicon github -o ci.yml. When it passes -o or --output with this file's path, chant workspace check --generated points that flag at a temporary file. Otherwise the generator writes in place and check restores the tree afterwards."
+        },
+        "sources": {
+          "type": "array",
+          "description": "The files or directories the generator reads, relative to the workspace root, since a generator often reads other members.",
+          "items": {
+            "$ref": "#/$defs/path"
+          }
+        },
+        "handWritten": {
+          "type": "object",
+          "description": "The file is kept by hand instead of regenerated. chant workspace check reports it with the reason and never runs its generator, and the lock classes it owned.",
+          "required": [
+            "because"
+          ],
+          "properties": {
+            "because": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "patternProperties": {
+            "^x-": true
+          },
+          "additionalProperties": false
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "pin": {
+      "description": "An npm package at an exact version, or a local plugin by path. integrity is a Subresource Integrity digest.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "package",
+            "version"
+          ],
+          "properties": {
+            "package": {
+              "type": "string",
+              "pattern": "^(@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$"
+            },
+            "version": {
+              "$ref": "#/$defs/version"
+            },
+            "integrity": {
+              "type": "string",
+              "pattern": "^sha(256|384|512)-[A-Za-z0-9+/]+={0,2}$"
+            }
+          },
+          "patternProperties": {
+            "^x-": true
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": [
+            "path"
+          ],
+          "properties": {
+            "path": {
+              "$ref": "#/$defs/dir"
+            },
+            "integrity": {
+              "type": "string",
+              "pattern": "^sha(256|384|512)-[A-Za-z0-9+/]+={0,2}$"
+            }
+          },
+          "patternProperties": {
+            "^x-": true
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}