@yuneta/gobj-ui 6.0.0 → 6.1.0

package/src/schema_to_c.test.js

@@ -0,0 +1,218 @@
+/***********************************************************************
+ *          schema_to_c.test.js
+ *
+ *      The stored schema written back as its C literal, pinned.
+ *
+ *      The test that matters is the ROUND TRIP: the emitted text is put
+ *      through the same two steps the yuno puts it through — the C
+ *      compiler's unescaping and helper_quote2doublequote() — and the
+ *      JSON that comes out must be the JSON that went in. Everything
+ *      else about the format is cosmetic; that is the part that decides
+ *      whether the paste compiles and opens.
+ ***********************************************************************/
+import { describe, test, expect } from "vitest";
+import { build_schema_model } from "./schema_model.js";
+import { schema_to_json, schema_to_c } from "./schema_to_c.js";
+
+
+/***************************************************************
+ *  What the yuno does to the literal before parsing it:
+ *      1. the C compiler resolves `\<newline>` continuations and
+ *         the `\\` / `\"` escapes,
+ *      2. helper_quote2doublequote() turns EVERY ' into ",
+ *      3. jansson parses what is left.
+ ***************************************************************/
+function load_like_the_yuno(source)
+{
+    const start = source.indexOf('"\\\n');
+    const end = source.lastIndexOf('";');
+    expect(start).toBeGreaterThan(0);
+    expect(end).toBeGreaterThan(start);
+
+    let body = source.slice(start + 3, end);
+
+    /*  Line continuations: a line ends with `\n\` + newline, which the
+        compiler turns into one newline.  */
+    let text = body.split("\\n\\\n").join("\n");
+    text = text.replace(/\\n\\$/, "");
+
+    /*  C escapes, innermost last: `\\` is a backslash, `\"` a quote.  */
+    let out = "";
+    for(let i = 0; i < text.length; i++) {
+        if(text[i] === "\\" && i + 1 < text.length) {
+            const next = text[i + 1];
+            if(next === "\\") {
+                out += "\\";
+                i++;
+                continue;
+            }
+            if(next === '"') {
+                out += '"';
+                i++;
+                continue;
+            }
+        }
+        out += text[i];
+    }
+
+    /*  helper_quote2doublequote(): every single quote, no exception.  */
+    out = out.split("'").join('"');
+
+    return JSON.parse(out);
+}
+
+
+const MODEL = build_schema_model({
+    treedbs: [{id: "treedb_sample", schema_version: 4}],
+    topics: [
+        {id: "treedb_sample.departments", value: "departments", order: 1, pkey: "id",
+         system_flag: "sf_string_key", topic_version: 2,
+         treedbs: ["treedbs^treedb_sample^topics"]},
+        {id: "treedb_sample.users", value: "users", order: 2, pkey: "id",
+         system_flag: "sf_string_key", topic_version: 3, pkey2s: "name",
+         treedbs: ["treedbs^treedb_sample^topics"]},
+    ],
+    cols: [
+        {id: "treedb_sample.departments.id", value: "id", order: 1, header: "Id",
+         fillspace: 20, type: "string", flag: ["persistent", "required"],
+         topics: ["topics^treedb_sample.departments^cols"]},
+        {id: "treedb_sample.departments.users", value: "users", order: 2,
+         header: "Users", fillspace: 20, type: "dict", flag: ["hook"],
+         hook: {users: "departments"},
+         topics: ["topics^treedb_sample.departments^cols"]},
+        {id: "treedb_sample.users.id", value: "id", order: 1, header: "Id",
+         fillspace: 20, type: "string", flag: ["persistent"],
+         topics: ["topics^treedb_sample.users^cols"]},
+        {id: "treedb_sample.users.name", value: "name", order: 2, header: "Name",
+         fillspace: 10, type: "string", flag: ["persistent", "writable"],
+         topics: ["topics^treedb_sample.users^cols"]},
+        {id: "treedb_sample.users.departments", value: "departments", order: 3,
+         header: "Departments", fillspace: 20, type: "array", flag: ["fkey"],
+         topics: ["topics^treedb_sample.users^cols"]},
+    ],
+});
+const TREEDB = MODEL.treedbs[0];
+
+
+describe("schema_to_json", () => {
+    const json = schema_to_json(TREEDB);
+
+    test("the shape of the literal: topics a LIST, cols a DICT", () => {
+        expect(Array.isArray(json.topics)).toBe(true);
+        expect(json.topics.map(t => t.id)).toEqual(["departments", "users"]);
+        expect(Array.isArray(json.topics[0].cols)).toBe(false);
+        expect(Object.keys(json.topics[1].cols)).toEqual(["id", "name", "departments"]);
+    });
+
+    test("a topic is named by its NAME, a column by its own", () => {
+        expect(json.topics[0].id).toBe("departments");
+        expect(json.topics[0].cols.users.type).toBe("dict");
+    });
+
+    test("no storage field survives the export", () => {
+        for(const key of ["value", "treedbs", "order"]) {
+            expect(json.topics[0][key]).toBeUndefined();
+        }
+        for(const key of ["value", "topics", "order"]) {
+            expect(json.topics[0].cols.id[key]).toBeUndefined();
+        }
+    });
+
+    test("a single pkey2 is written bare, as the literals write it", () => {
+        expect(json.topics[1].pkey2s).toBe("name");
+    });
+
+    test("the keys come out in the order the .c files declare them", () => {
+        expect(Object.keys(json.topics[1]).slice(0, 3)).toEqual(["id", "pkey", "pkey2s"]);
+        expect(Object.keys(json.topics[0].cols.id))
+            .toEqual(["header", "fillspace", "type", "flag"]);
+    });
+
+    test("no treedb is null, not a throw", () => {
+        expect(schema_to_json(null)).toBe(null);
+    });
+});
+
+describe("schema_to_c — the round trip", () => {
+    const source = schema_to_c(TREEDB);
+
+    test("it is a C array declaration with the conventional name", () => {
+        expect(source.startsWith("static char treedb_schema_sample[]= \"\\\n")).toBe(true);
+        expect(source.trimEnd().endsWith('";')).toBe(true);
+    });
+
+    test("every line carries the continuation", () => {
+        const body = source.split("\n").slice(1, -2);
+        for(const line of body) {
+            expect(line.endsWith("\\n\\")).toBe(true);
+        }
+    });
+
+    test("loaded the way the yuno loads it, it is the schema it came from", () => {
+        expect(load_like_the_yuno(source)).toEqual(schema_to_json(TREEDB));
+    });
+
+    test("the caller can name the array and set the continuation column", () => {
+        const custom = schema_to_c(TREEDB, {var_name: "my_schema", pad: 40});
+        expect(custom.startsWith("static char my_schema[]=")).toBe(true);
+        expect(load_like_the_yuno(custom)).toEqual(schema_to_json(TREEDB));
+    });
+
+    test("a version is quoted, a fillspace is not — as the literals write them", () => {
+        expect(source).toContain("'schema_version': '4'");
+        expect(source).toContain("'topic_version': '2'");
+        expect(source).toContain("'fillspace': 20");
+    });
+
+    test("a boolean stays a boolean", () => {
+        const model = build_schema_model({
+            treedbs: [{id: "treedb_x", schema_version: 1}],
+            topics: [{id: "treedb_x.t", value: "t", system_topic: true,
+                      treedbs: ["treedbs^treedb_x^topics"]}],
+            cols: [{id: "treedb_x.t.id", value: "id", type: "string",
+                    topics: ["topics^treedb_x.t^cols"]}],
+        });
+        const src = schema_to_c(model.treedbs[0]);
+        expect(src).toContain("'system_topic': true");
+        expect(load_like_the_yuno(src).topics[0].system_topic).toBe(true);
+    });
+
+    test("no treedb is an empty string, not a broken declaration", () => {
+        expect(schema_to_c(null)).toBe("");
+    });
+});
+
+describe("the characters that cannot be written as themselves", () => {
+    function with_header(header)
+    {
+        const model = build_schema_model({
+            treedbs: [{id: "treedb_x", schema_version: 1}],
+            topics: [{id: "treedb_x.t", value: "t", treedbs: ["treedbs^treedb_x^topics"]}],
+            cols: [{id: "treedb_x.t.id", value: "id", type: "string", header: header,
+                    topics: ["topics^treedb_x.t^cols"]}],
+        });
+        return schema_to_c(model.treedbs[0]);
+    }
+
+    test("a SINGLE QUOTE survives — the pass that rewrites them cannot see \\u0027", () => {
+        const src = with_header("Client's name");
+        expect(src).toContain("\\\\u0027");
+        expect(load_like_the_yuno(src).topics[0].cols.id.header).toBe("Client's name");
+    });
+
+    test("a double quote survives both layers", () => {
+        const src = with_header('Say "hi"');
+        expect(load_like_the_yuno(src).topics[0].cols.id.header).toBe('Say "hi"');
+    });
+
+    test("a backslash survives both layers", () => {
+        const src = with_header("a\\b");
+        expect(load_like_the_yuno(src).topics[0].cols.id.header).toBe("a\\b");
+    });
+
+    test("all three at once", () => {
+        const header = 'a\\b "c" d\'e';
+        expect(load_like_the_yuno(with_header(header)).topics[0].cols.id.header)
+            .toBe(header);
+    });
+});

package/src/schema_validate.js

@@ -0,0 +1,289 @@
+/***********************************************************************
+ *          schema_validate.js
+ *
+ *      What is wrong with a schema, BEFORE the yuno is restarted to
+ *      read it.
+ *
+ *      Applying a schema is restarting the yuno that owns it. A schema
+ *      the treedb refuses therefore costs an outage to discover, and
+ *      the message arrives in that yuno's log, on the node, minutes
+ *      after the edit that caused it. Everything checked here is
+ *      checkable from the records alone.
+ *
+ *      TWO CLASSES OF FINDING, and the difference matters:
+ *
+ *        `error`   the treedb will refuse the topic, or the link the
+ *                  operator drew does nothing at all. Restarting on
+ *                  this is an outage with no gain.
+ *        `warning` the schema opens and something is not what it looks
+ *                  like — an unbumped `topic_version` masking the whole
+ *                  edit is the one that costs the most time, because
+ *                  the restart SUCCEEDS and the change is simply not
+ *                  there.
+ *
+ *      Every `code` is an i18n key: the caller renders, this decides.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {
+    col_flags,
+    col_hook,
+    col_enum,
+    topic_pkey2s,
+} from "./schema_model.js";
+
+
+/*  What a column may be typed as: the `type` enum of the `cols` topic
+ *  (treedb_system_schema.c). A type outside it is refused by the
+ *  validator the treedb builds from that same enum.  */
+const COL_TYPES = [
+    "string", "integer", "object", "dict", "array", "list",
+    "real", "boolean", "blob"
+];
+
+/*  What a HOOK may be typed as: a hook holds its children, so it is a
+ *  collection. `{}` (dict) for N unique children, `[]` (list) for n.  */
+const HOOK_TYPES = ["dict", "object", "list", "array"];
+
+/*  What a FKEY may be typed as: one parent is a string, n parents a
+ *  collection.  */
+const FKEY_TYPES = ["string", "dict", "object", "list", "array"];
+
+
+/***************************************************************
+ *  validate_schema(treedb, options) -> [finding, ...]
+ *
+ *      treedb    one entry of build_schema_model().treedbs
+ *      options   {
+ *          written_topics: [topic id, ...]   topics this session wrote
+ *          baseline: {topic id: topic_version}   version at load time
+ *      }
+ *
+ *      finding   {severity, code, treedb, topic, col, detail}
+ *
+ *      Findings come out worst-first, so a caller that shows three
+ *      lines shows the three that matter.
+ ***************************************************************/
+function validate_schema(treedb, options)
+{
+    let findings = [];
+    let opts = options || {};
+    let written = Array.isArray(opts.written_topics) ? opts.written_topics : [];
+    let baseline = opts.baseline || {};
+
+    if(!treedb || !Array.isArray(treedb.topics)) {
+        return findings;
+    }
+
+    let add = (severity, code, topic, col, detail) => {
+        findings.push({
+            severity: severity,
+            code:     code,
+            treedb:   treedb.id,
+            topic:    topic || "",
+            col:      col || "",
+            detail:   detail || ""
+        });
+    };
+
+    /*  Which topics exist, and which columns each one has: a hook is
+     *  checked against the CHILD topic, so both are needed up front.  */
+    let topic_by_name = {};
+    for(let topic of treedb.topics) {
+        topic_by_name[topic.name] = topic;
+    }
+
+    if(treedb.topics.length === 0) {
+        add("warning", "schema has no topic", "", "", "");
+    }
+
+    for(let topic of treedb.topics) {
+        let col_names = topic.cols.map(c => c.name);
+
+        if(topic.cols.length === 0) {
+            add("error", "topic has no column", topic.name, "", "");
+        }
+
+        /*  The pkey is the column every record is stored under: naming
+         *  one that is not there is a topic that does not open.  */
+        let pkey = topic.pkey || "id";
+        if(col_names.indexOf(pkey) < 0) {
+            add("error", "pkey names no column", topic.name, "", pkey);
+        }
+        for(let pkey2 of topic_pkey2s(topic.record)) {
+            if(col_names.indexOf(pkey2) < 0) {
+                add("error", "pkey2 names no column", topic.name, "", pkey2);
+            }
+        }
+
+        /*  A version that did not move republishes nothing: the stored
+         *  topic_cols.json masks the whole edit and the restart looks
+         *  like it worked.  */
+        if(written.indexOf(topic.id) >= 0) {
+            let before = baseline[topic.id];
+            if(before !== undefined && String(before) === String(topic.topic_version)) {
+                add("warning", "topic version not bumped", topic.name, "",
+                    String(topic.topic_version));
+            }
+        }
+
+        for(let col of topic.cols) {
+            let flags = col_flags(col.record);
+            let type = col.record ? col.record.type : "";
+            let is_hook = flags.indexOf("hook") >= 0;
+            let is_fkey = flags.indexOf("fkey") >= 0;
+
+            if(!type) {
+                add("error", "column has no type", topic.name, col.name, "");
+            } else if(COL_TYPES.indexOf(type) < 0) {
+                add("error", "unknown column type", topic.name, col.name, type);
+            }
+
+            if(flags.indexOf("enum") >= 0 && col_enum(col.record).length === 0) {
+                add("error", "enum column has no enum", topic.name, col.name, "");
+            }
+
+            if(is_hook) {
+                if(HOOK_TYPES.indexOf(type) < 0) {
+                    add("error", "hook must be a collection", topic.name, col.name, type);
+                }
+                let hook = col_hook(col.record);
+                if(!hook || Object.keys(hook).length === 0) {
+                    /*  A hook with no mapping links nothing, and the write
+                     *  that made it succeeded.  */
+                    add("error", "hook has no mapping", topic.name, col.name, "");
+                } else {
+                    for(let [child_topic, fkey_col] of Object.entries(hook)) {
+                        let child = topic_by_name[child_topic];
+                        if(!child) {
+                            add("error", "hook names no topic", topic.name, col.name,
+                                child_topic);
+                            continue;
+                        }
+                        let child_col = null;
+                        for(let c of child.cols) {
+                            if(c.name === fkey_col) {
+                                child_col = c;
+                                break;
+                            }
+                        }
+                        if(!child_col) {
+                            add("error", "hook names no fkey column", topic.name, col.name,
+                                `${child_topic}.${fkey_col}`);
+                            continue;
+                        }
+                        if(col_flags(child_col.record).indexOf("fkey") < 0) {
+                            /*  The column exists and is not a fkey: the link
+                             *  saves nothing and the graph draws no edge.  */
+                            add("error", "hook target is not a fkey", topic.name, col.name,
+                                `${child_topic}.${fkey_col}`);
+                        }
+                    }
+                }
+            }
+
+            if(is_fkey && FKEY_TYPES.indexOf(type) < 0) {
+                add("error", "fkey has a bad type", topic.name, col.name, type);
+            }
+        }
+    }
+
+    /*  How many hooks name each fkey column. Both answers are a
+     *  finding: NONE and the parent side of the link was renamed or
+     *  deleted, so the references are written by nobody; TWO and the
+     *  treedb refuses to open the schema ("Only can be one fkey",
+     *  tr_treedb.c) because the column cannot hold both parents.  */
+    let hooked = {};
+    for(let topic of treedb.topics) {
+        for(let col of topic.cols) {
+            let hook = col_hook(col.record);
+            if(!hook) {
+                continue;
+            }
+            for(let [child_topic, fkey_col] of Object.entries(hook)) {
+                let key = `${child_topic}.${fkey_col}`;
+                hooked[key] = (hooked[key] || 0) + 1;
+            }
+        }
+    }
+    for(let topic of treedb.topics) {
+        for(let col of topic.cols) {
+            if(col_flags(col.record).indexOf("fkey") < 0) {
+                continue;
+            }
+            let count = hooked[`${topic.name}.${col.name}`] || 0;
+            if(count === 0) {
+                add("warning", "fkey with no hook", topic.name, col.name, "");
+            } else if(count > 1) {
+                add("error", "fkey named by two hooks", topic.name, col.name, String(count));
+            }
+        }
+    }
+
+    findings.sort((a, b) => {
+        if(a.severity !== b.severity) {
+            return a.severity === "error" ? -1 : 1;
+        }
+        return 0;
+    });
+    return findings;
+}
+
+/***************************************************************
+ *  The same over a whole model, plus what belongs to no treedb:
+ *  an orphan is a leftover of a deletion and the editor is where
+ *  it is found.
+ ***************************************************************/
+function validate_model(model, options)
+{
+    let findings = [];
+
+    if(!model) {
+        return findings;
+    }
+    for(let treedb of (model.treedbs || [])) {
+        findings = findings.concat(validate_schema(treedb, options));
+    }
+    for(let topic of (model.orphan_topics || [])) {
+        findings.push({
+            severity: "warning", code: "topic belongs to no treedb",
+            treedb: "", topic: topic.name, col: "", detail: topic.id
+        });
+    }
+    for(let col of (model.orphan_cols || [])) {
+        findings.push({
+            severity: "warning", code: "column belongs to no topic",
+            treedb: "", topic: "", col: col.name, detail: col.id
+        });
+    }
+    return findings;
+}
+
+/***************************************************************
+ *  Is there anything that should stop an Apply? Warnings do not:
+ *  the operator may know better, and an unbumped version is worth
+ *  saying and not worth refusing.
+ ***************************************************************/
+function has_errors(findings)
+{
+    if(!Array.isArray(findings)) {
+        return false;
+    }
+    for(let f of findings) {
+        if(f && f.severity === "error") {
+            return true;
+        }
+    }
+    return false;
+}
+
+
+export {
+    COL_TYPES,
+    HOOK_TYPES,
+    FKEY_TYPES,
+    validate_schema,
+    validate_model,
+    has_errors,
+};