@toist/spec 0.2.0

package/src/yaml.ts

@@ -0,0 +1,61 @@
+// 2121
+// Strict YAML loader for pipeline files.
+//
+// Per pipeline-spec.md §1: anchors, aliases, merge keys, and multi-document
+// files are rejected at spec-load. Reuse is a spec-level concern (kinds, refs)
+// not a YAML-syntax concern, and round-trip isomorphism with the UI editor
+// requires this discipline.
+
+import YAML from "yaml"
+
+export class YamlError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "YamlError"
+  }
+}
+
+/**
+ * Parse a YAML pipeline source. Returns a plain JS object on success;
+ * throws YamlError on syntax error, multi-document files, anchors, aliases,
+ * or merge keys.
+ */
+export function parse(src: string): unknown {
+  const docs = YAML.parseAllDocuments(src, { strict: true })
+  if (docs.length === 0) throw new YamlError("empty YAML document")
+  if (docs.length > 1) {
+    throw new YamlError(
+      "multi-document YAML files (--- separator) are not allowed; one file = one pipeline",
+    )
+  }
+
+  const doc = docs[0]
+  if (doc.errors.length > 0) {
+    throw new YamlError(`YAML parse error: ${doc.errors[0].message}`)
+  }
+
+  // Walk the document AST checking for anchors, aliases, and merge keys.
+  YAML.visit(doc, {
+    Alias() {
+      throw new YamlError(
+        "YAML aliases (*name) are not allowed; reuse via spec-level kinds or `$ref` instead",
+      )
+    },
+    Pair(_, pair) {
+      // Merge keys are pairs whose key is the special "<<" tag.
+      const key = pair.key
+      if (key && typeof key === "object" && "value" in key && key.value === "<<") {
+        throw new YamlError("YAML merge keys (<<:) are not allowed")
+      }
+    },
+    Node(_, node) {
+      if (node && typeof node === "object" && "anchor" in node && node.anchor) {
+        throw new YamlError(
+          `YAML anchors (&${node.anchor}) are not allowed; reuse via spec-level kinds or \`$ref\` instead`,
+        )
+      }
+    },
+  })
+
+  return doc.toJSON()
+}