gofish-ir 0.1.0

package/dist/frontend/validate.js

@@ -0,0 +1,591 @@
+// <gofish-wiki> AUTO-GENERATED — see covers: in the essay; run `pnpm --filter docs sync-backlinks`
+// @wiki Frontend IR — /internals/frontend/serialization
+// </gofish-wiki>
+/**
+ * Runtime validator for the GoFish frontend IR.
+ *
+ * Hand-rolled, dependency-free. Strict mode rejects unknown fields (used in
+ * CI and tests); the default permissive mode ignores them, suitable for
+ * forward-compatible reading.
+ */
+import { COMBINATOR_MARK_TYPES, LEAF_MARK_TYPES, OPERATOR_TYPES, } from "./schema.js";
+/** Validate a document against the frontend-IR schema. */
+export function validate(doc, options = {}) {
+    const ctx = {
+        strict: options.strict === true,
+        errors: [],
+    };
+    walkDocument(doc, "$", ctx);
+    return ctx.errors.length === 0
+        ? { valid: true }
+        : { valid: false, errors: ctx.errors };
+}
+function walkDocument(node, path, ctx) {
+    if (!isObject(node)) {
+        ctx.errors.push({ path, message: "expected object" });
+        return;
+    }
+    expectField(node, "irVersion", path, ctx, (v, p) => {
+        if (v !== 0)
+            ctx.errors.push({
+                path: p,
+                message: `irVersion must be 0, got ${JSON.stringify(v)}`,
+            });
+    });
+    expectField(node, "ir", path, ctx, (v, p) => {
+        if (v !== "gofish-frontend")
+            ctx.errors.push({
+                path: p,
+                message: `ir must be "gofish-frontend", got ${JSON.stringify(v)}`,
+            });
+    });
+    optionalField(node, "$schema", path, ctx, expectString);
+    expectField(node, "root", path, ctx, walkRoot);
+    if (ctx.strict) {
+        rejectUnknown(node, ["irVersion", "ir", "$schema", "root"], path, ctx);
+    }
+}
+function walkRoot(node, path, ctx) {
+    if (!isObject(node)) {
+        ctx.errors.push({ path, message: "expected object" });
+        return;
+    }
+    switch (node.type) {
+        case "chart":
+            walkChart(node, path, ctx);
+            return;
+        case "layer":
+            walkLayer(node, path, ctx);
+            return;
+        case "raw-mark":
+            walkRawMark(node, path, ctx);
+            return;
+        default:
+            ctx.errors.push({
+                path: `${path}.type`,
+                message: `root type must be "chart" | "layer" | "raw-mark", got ${JSON.stringify(node.type)}`,
+            });
+    }
+}
+function walkChart(node, path, ctx) {
+    walkBaseFields(node, path, ctx);
+    optionalField(node, "data", path, ctx, (v, p) => {
+        if (v === null)
+            return;
+        walkData(v, p, ctx);
+    });
+    optionalField(node, "operators", path, ctx, (v, p) => walkArray(v, p, ctx, walkOperator));
+    expectField(node, "mark", path, ctx, walkMark);
+    optionalField(node, "options", path, ctx, expectObject);
+    optionalField(node, "zOrder", path, ctx, expectNumber);
+    if (ctx.strict) {
+        rejectUnknown(node, [
+            "type",
+            "data",
+            "operators",
+            "mark",
+            "options",
+            "zOrder",
+            "origin",
+            "meta",
+        ], path, ctx);
+    }
+}
+function walkLayer(node, path, ctx) {
+    walkBaseFields(node, path, ctx);
+    expectField(node, "charts", path, ctx, (v, p) => walkArray(v, p, ctx, walkRootChart));
+    optionalField(node, "options", path, ctx, expectObject);
+    if (ctx.strict) {
+        rejectUnknown(node, ["type", "charts", "options", "origin", "meta"], path, ctx);
+    }
+}
+function walkRootChart(node, path, ctx) {
+    if (!isObject(node) || node.type !== "chart") {
+        ctx.errors.push({
+            path,
+            message: 'layer children must be charts (type === "chart")',
+        });
+        return;
+    }
+    walkChart(node, path, ctx);
+}
+function walkRawMark(node, path, ctx) {
+    walkBaseFields(node, path, ctx);
+    expectField(node, "mark", path, ctx, walkMark);
+    optionalField(node, "options", path, ctx, expectObject);
+    if (ctx.strict) {
+        rejectUnknown(node, ["type", "mark", "options", "origin", "meta"], path, ctx);
+    }
+}
+function walkData(node, path, ctx) {
+    if (!isObject(node)) {
+        ctx.errors.push({ path, message: "expected object" });
+        return;
+    }
+    switch (node.type) {
+        case "inline":
+            expectField(node, "rows", path, ctx, (v, p) => {
+                if (!Array.isArray(v))
+                    ctx.errors.push({ path: p, message: "rows must be an array" });
+            });
+            if (ctx.strict)
+                rejectUnknown(node, ["type", "rows"], path, ctx);
+            return;
+        case "select":
+            expectField(node, "layer", path, ctx, expectString);
+            if (ctx.strict)
+                rejectUnknown(node, ["type", "layer"], path, ctx);
+            return;
+        case "external":
+            optionalField(node, "id", path, ctx, expectString);
+            if (ctx.strict)
+                rejectUnknown(node, ["type", "id"], path, ctx);
+            return;
+        default:
+            ctx.errors.push({
+                path: `${path}.type`,
+                message: `data type must be "inline" | "select" | "external", got ${JSON.stringify(node.type)}`,
+            });
+    }
+}
+function walkOperator(node, path, ctx) {
+    if (!isObject(node)) {
+        ctx.errors.push({ path, message: "expected object" });
+        return;
+    }
+    if (typeof node.type !== "string" ||
+        !OPERATOR_TYPES.includes(node.type)) {
+        ctx.errors.push({
+            path: `${path}.type`,
+            message: `operator type must be one of ${OPERATOR_TYPES.join(", ")}, got ${JSON.stringify(node.type)}`,
+        });
+        return;
+    }
+    walkBaseFields(node, path, ctx);
+    // Per-type field validation. Each operator has a known set of optional
+    // and required fields; in strict mode, unknown fields are rejected.
+    const knownFields = {
+        derive: ["type", "lambdaId", "origin", "meta"],
+        spread: [
+            "type",
+            "by",
+            "dir",
+            "spacing",
+            "alignment",
+            "sharedScale",
+            "mode",
+            "reverse",
+            "origin",
+            "meta",
+        ],
+        stack: [
+            "type",
+            "by",
+            "dir",
+            "alignment",
+            "sharedScale",
+            "mode",
+            "reverse",
+            "origin",
+            "meta",
+        ],
+        group: ["type", "by", "origin", "meta"],
+        scatter: [
+            "type",
+            "by",
+            "x",
+            "y",
+            "xMin",
+            "xMax",
+            "yMin",
+            "yMax",
+            "alignment",
+            "origin",
+            "meta",
+        ],
+        table: ["type", "by", "spacing", "numCols", "origin", "meta"],
+        log: ["type", "label", "origin", "meta"],
+    };
+    switch (node.type) {
+        case "derive":
+            optionalField(node, "lambdaId", path, ctx, expectString);
+            break;
+        case "spread":
+        case "stack":
+            optionalField(node, "by", path, ctx, expectString);
+            optionalField(node, "dir", path, ctx, (v, p) => {
+                if (v !== "x" && v !== "y")
+                    ctx.errors.push({
+                        path: p,
+                        message: `dir must be "x" | "y", got ${JSON.stringify(v)}`,
+                    });
+            });
+            optionalField(node, "spacing", path, ctx, expectNumber);
+            optionalField(node, "alignment", path, ctx, expectString);
+            optionalField(node, "sharedScale", path, ctx, expectBoolean);
+            optionalField(node, "reverse", path, ctx, expectBoolean);
+            optionalField(node, "mode", path, ctx, (v, p) => {
+                if (v !== "edge" && v !== "center")
+                    ctx.errors.push({
+                        path: p,
+                        message: `mode must be "edge" | "center"`,
+                    });
+            });
+            break;
+        case "group":
+            expectField(node, "by", path, ctx, expectString);
+            break;
+        case "scatter":
+            optionalField(node, "by", path, ctx, expectString);
+            for (const k of ["x", "y", "xMin", "xMax", "yMin", "yMax"]) {
+                optionalField(node, k, path, ctx, walkChannelValue);
+            }
+            break;
+        case "table":
+            // `by` is required: the table operator can't run without an
+            // {x, y} field-name pair (Python's table() raises if missing).
+            expectField(node, "by", path, ctx, (v, p) => {
+                if (!isObject(v)) {
+                    ctx.errors.push({ path: p, message: "table.by must be an object" });
+                    return;
+                }
+                expectField(v, "x", p, ctx, expectString);
+                expectField(v, "y", p, ctx, expectString);
+            });
+            optionalField(node, "spacing", path, ctx, (v, p) => {
+                if (typeof v === "number")
+                    return;
+                if (Array.isArray(v) &&
+                    v.length === 2 &&
+                    v.every((n) => typeof n === "number"))
+                    return;
+                ctx.errors.push({
+                    path: p,
+                    message: "table.spacing must be a number or [number, number]",
+                });
+            });
+            optionalField(node, "numCols", path, ctx, expectNumber);
+            break;
+        case "log":
+            optionalField(node, "label", path, ctx, expectString);
+            break;
+    }
+    if (ctx.strict) {
+        rejectUnknown(node, knownFields[node.type] ?? ["type"], path, ctx);
+    }
+}
+/**
+ * A channel value: bare primitive, the existing `{type:"datum"}` wrapper,
+ * the new `{type:"field"|"literal"}` constructors, or a Python-bridge
+ * sentinel. Permissive — only catches obviously-wrong shapes.
+ */
+function walkChannelValue(value, path, ctx) {
+    if (value === null)
+        return;
+    if (typeof value === "string")
+        return;
+    if (typeof value === "number")
+        return;
+    if (typeof value === "boolean")
+        return;
+    if (typeof value !== "object") {
+        ctx.errors.push({
+            path,
+            message: `channel value must be primitive or tagged object, got ${typeNameOf(value)}`,
+        });
+        return;
+    }
+    // Object form: one of the recognized tagged shapes.
+    const obj = value;
+    if ("__gofish_lambda" in obj)
+        return; // Python-bridge sentinel
+    if (obj.type === "datum")
+        return;
+    if (obj.type === "field") {
+        if (typeof obj.name !== "string") {
+            ctx.errors.push({
+                path: `${path}.name`,
+                message: 'field channel must have a string "name"',
+            });
+        }
+        return;
+    }
+    if (obj.type === "literal") {
+        if (!("value" in obj)) {
+            ctx.errors.push({
+                path: `${path}.value`,
+                message: 'literal channel must have a "value" field',
+            });
+        }
+        return;
+    }
+    // Permissive fallback: allow unknown object shapes for forward-compat.
+}
+function walkMark(node, path, ctx) {
+    if (!isObject(node)) {
+        ctx.errors.push({ path, message: "expected object" });
+        return;
+    }
+    const t = node.type;
+    if (typeof t !== "string") {
+        ctx.errors.push({
+            path: `${path}.type`,
+            message: "mark type must be a string",
+        });
+        return;
+    }
+    if (t === "ref") {
+        walkRefMark(node, path, ctx);
+        return;
+    }
+    if (node.__combinator === true) {
+        walkCombinatorMark(node, path, ctx);
+        return;
+    }
+    if (LEAF_MARK_TYPES.includes(t)) {
+        walkLeafMark(node, path, ctx);
+        return;
+    }
+    ctx.errors.push({
+        path: `${path}.type`,
+        message: `unrecognized mark type ${JSON.stringify(t)}`,
+    });
+}
+function walkRefMark(node, path, ctx) {
+    walkBaseFields(node, path, ctx);
+    expectField(node, "selection", path, ctx, (v, p) => {
+        if (typeof v !== "string" && !Array.isArray(v)) {
+            ctx.errors.push({
+                path: p,
+                message: "ref.selection must be a string or array",
+            });
+        }
+    });
+    optionalField(node, "name", path, ctx, expectNameOrToken);
+    optionalField(node, "label", path, ctx, walkLabel);
+    optionalField(node, "zOrder", path, ctx, expectNumber);
+    if (ctx.strict) {
+        rejectUnknown(node, ["type", "selection", "name", "label", "zOrder", "origin", "meta"], path, ctx);
+    }
+}
+function walkCombinatorMark(node, path, ctx) {
+    if (!COMBINATOR_MARK_TYPES.includes(node.type)) {
+        ctx.errors.push({
+            path: `${path}.type`,
+            message: `combinator mark type must be one of ${COMBINATOR_MARK_TYPES.join(", ")}`,
+        });
+    }
+    walkBaseFields(node, path, ctx);
+    optionalField(node, "options", path, ctx, expectObject);
+    expectField(node, "children", path, ctx, (v, p) => walkArray(v, p, ctx, walkMark));
+    optionalField(node, "name", path, ctx, expectNameOrToken);
+    optionalField(node, "label", path, ctx, walkLabel);
+    optionalField(node, "constraints", path, ctx, (v, p) => walkArray(v, p, ctx, walkConstraint));
+    optionalField(node, "zOrder", path, ctx, expectNumber);
+    if (ctx.strict) {
+        rejectUnknown(node, [
+            "type",
+            "__combinator",
+            "options",
+            "children",
+            "name",
+            "label",
+            "constraints",
+            "zOrder",
+            "origin",
+            "meta",
+        ], path, ctx);
+    }
+}
+function walkLeafMark(node, path, ctx) {
+    walkBaseFields(node, path, ctx);
+    optionalField(node, "name", path, ctx, expectNameOrToken);
+    optionalField(node, "label", path, ctx, walkLabel);
+    optionalField(node, "constraints", path, ctx, (v, p) => walkArray(v, p, ctx, walkConstraint));
+    optionalField(node, "zOrder", path, ctx, expectNumber);
+    // Channel-valued props are unrestricted in v0 (mirrors widget IR).
+    // Strict mode does NOT reject unknown fields on leaf marks, because the
+    // entire point of a leaf is to carry channel-valued props with arbitrary
+    // names (h, w, fill, x, y, etc.).
+}
+function walkLabel(node, path, ctx) {
+    // Shorthand forms (matching the JS API):
+    //   label: true   → "label with default settings"
+    //   label: "field" → "label with this field accessor, defaults elsewhere"
+    if (typeof node === "boolean")
+        return;
+    if (typeof node === "string")
+        return;
+    if (!isObject(node)) {
+        ctx.errors.push({
+            path,
+            message: "expected object, boolean, or string",
+        });
+        return;
+    }
+    expectField(node, "accessor", path, ctx, expectString);
+    optionalField(node, "position", path, ctx, expectString);
+    optionalField(node, "fontSize", path, ctx, expectNumber);
+    optionalField(node, "color", path, ctx, expectString);
+    optionalField(node, "offset", path, ctx, expectNumber);
+    optionalField(node, "minSpace", path, ctx, expectNumber);
+    optionalField(node, "rotate", path, ctx, expectNumber);
+    if (ctx.strict) {
+        rejectUnknown(node, [
+            "accessor",
+            "position",
+            "fontSize",
+            "color",
+            "offset",
+            "minSpace",
+            "rotate",
+        ], path, ctx);
+    }
+}
+function walkConstraint(node, path, ctx) {
+    if (!isObject(node)) {
+        ctx.errors.push({ path, message: "expected object" });
+        return;
+    }
+    const t = node.type;
+    if (t !== "align" && t !== "distribute" && t !== "zAbove" && t !== "zBelow") {
+        ctx.errors.push({
+            path: `${path}.type`,
+            message: `constraint type must be "align" | "distribute" | "zAbove" | "zBelow"`,
+        });
+        return;
+    }
+    expectField(node, "refs", path, ctx, (v, p) => {
+        if (!Array.isArray(v) || !v.every((x) => typeof x === "string")) {
+            ctx.errors.push({ path: p, message: "refs must be an array of strings" });
+        }
+    });
+    optionalField(node, "options", path, ctx, expectObject);
+    if (ctx.strict) {
+        rejectUnknown(node, ["type", "refs", "options"], path, ctx);
+    }
+}
+function walkBaseFields(node, path, ctx) {
+    optionalField(node, "origin", path, ctx, walkOrigin);
+    optionalField(node, "meta", path, ctx, walkMeta);
+}
+function walkOrigin(node, path, ctx) {
+    if (!isObject(node)) {
+        ctx.errors.push({ path, message: "origin must be an object" });
+        return;
+    }
+    optionalField(node, "name", path, ctx, expectNameOrToken);
+    optionalField(node, "stack", path, ctx, expectString);
+    if (ctx.strict)
+        rejectUnknown(node, ["name", "stack"], path, ctx);
+}
+function walkMeta(node, path, _ctx) {
+    if (!isObject(node)) {
+        _ctx.errors.push({ path, message: "meta must be an object" });
+        return;
+    }
+    // Meta is intentionally open — additional keys are reserved for future
+    // passes. v0 doesn't enforce per-key shapes; that lands with the passes
+    // that populate them.
+}
+// ---------------------------------------------------------------------------
+// Field helpers
+// ---------------------------------------------------------------------------
+function expectField(obj, key, parentPath, ctx, check) {
+    const childPath = `${parentPath}.${key}`;
+    if (!(key in obj)) {
+        ctx.errors.push({
+            path: childPath,
+            message: `required field "${key}" is missing`,
+        });
+        return;
+    }
+    check(obj[key], childPath, ctx);
+}
+function optionalField(obj, key, parentPath, ctx, check) {
+    // Treat both `undefined` and explicit `null` as "absent". Python's
+    // `to_dict()` emits `null` for several optional fields (data, zOrder,
+    // ...) rather than omitting them.
+    if (!(key in obj) || obj[key] === undefined || obj[key] === null)
+        return;
+    check(obj[key], `${parentPath}.${key}`, ctx);
+}
+function walkArray(v, path, ctx, walkItem) {
+    if (!Array.isArray(v)) {
+        ctx.errors.push({ path, message: "expected array" });
+        return;
+    }
+    v.forEach((item, i) => walkItem(item, `${path}[${i}]`, ctx));
+}
+function rejectUnknown(obj, knownKeys, path, ctx) {
+    for (const k of Object.keys(obj)) {
+        if (!knownKeys.includes(k)) {
+            ctx.errors.push({
+                path: `${path}.${k}`,
+                message: `unknown field "${k}" (strict)`,
+            });
+        }
+    }
+}
+function expectString(value, path, ctx) {
+    if (typeof value !== "string") {
+        ctx.errors.push({
+            path,
+            message: `expected string, got ${typeNameOf(value)}`,
+        });
+    }
+}
+function expectNumber(value, path, ctx) {
+    if (typeof value !== "number") {
+        ctx.errors.push({
+            path,
+            message: `expected number, got ${typeNameOf(value)}`,
+        });
+    }
+}
+function expectBoolean(value, path, ctx) {
+    if (typeof value !== "boolean") {
+        ctx.errors.push({
+            path,
+            message: `expected boolean, got ${typeNameOf(value)}`,
+        });
+    }
+}
+/**
+ * A name field may be a string or a Python-bridge token sentinel
+ * (`{__gofish_token, __tag}`) used to encode hygienic names across the
+ * widget bridge. The deserializer resolves the sentinel to a runtime
+ * Token at chart-build time.
+ */
+function expectNameOrToken(value, path, ctx) {
+    if (typeof value === "string")
+        return;
+    if (typeof value === "object" &&
+        value !== null &&
+        typeof value.__gofish_token === "string" &&
+        typeof value.__tag === "string") {
+        return;
+    }
+    ctx.errors.push({
+        path,
+        message: `expected string or token sentinel, got ${typeNameOf(value)}`,
+    });
+}
+function expectObject(value, path, ctx) {
+    if (!isObject(value)) {
+        ctx.errors.push({
+            path,
+            message: `expected object, got ${typeNameOf(value)}`,
+        });
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function typeNameOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * as Frontend from "./frontend/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export * as Frontend from "./frontend/index.js";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "gofish-ir",
+  "version": "0.1.0",
+  "description": "Serialized intermediate representation (IR) for GoFish chart specifications.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./frontend": {
+      "import": "./dist/frontend/index.js",
+      "types": "./dist/frontend/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "gofish",
+    "ir",
+    "schema",
+    "visualization"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gofish-graphics/gofish-graphics"
+  },
+  "scripts": {
+    "build": "tsc && tsx scripts/emit-jsonschema.ts",
+    "test": "tsx src/tests/schema.test.ts",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}