@yuneta/gobj-ui 7.23.195 → 7.23.197

package/src/schema_to_diagram.js

@@ -0,0 +1,301 @@
+/***********************************************************************
+ *          schema_to_diagram.js
+ *
+ *      The graph of a treedb schema, drawn as text.
+ *
+ *      It is the comment that heads every `treedb_schema_<db>.c`: one
+ *      box per topic, in the order the schema declares them, a row per
+ *      column, and every hook -> fkey link drawn as a line from the
+ *      hook's row (`◀`) to the fkey's row. It is DERIVED from the
+ *      schema, never drawn by hand, so the file that holds the literal
+ *      can be replaced whole with an export and its picture is never
+ *      behind it.
+ *
+ *      Each link runs down its own LANE to the right of the boxes, the
+ *      shorter links nearer to them, so no search is needed to lay it
+ *      out: the only ambiguity left is where a line crosses a lane that
+ *      is in use, and that is drawn as a junction.
+ *
+ *      The input is the schema as its literal holds it (what
+ *      schema_to_json() answers, or the parsed literal itself):
+ *          {id, schema_version, topics: [{id, pkey2s, tkey, main_topic,
+ *                                         cols: {name: {type, flag, hook}}}]}
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+
+/*  Where the boxes start, and their narrowest inside: the widths of
+ *  the diagrams drawn by hand before this, so a generated one reads
+ *  like them.  */
+const INDENT = 8;
+const MIN_INNER = 27;
+
+/*  From a box's right edge to its first lane, and between lanes.  */
+const LANE_GAP = 4;
+
+const LEGEND = [
+    "{}  dict hook   (N unique children)",
+    "[]  list hook   (n not-unique children)",
+    "()  string hook (1 unique child)",
+    "(↖) 1 fkey      (1 parent)",
+    "[↖] n fkeys     (n parents)",
+    "{↖} N fkeys     (N parents)",
+    "",
+    "(2) pkey2 - secondary key",
+    "(t) tkey  - time key",
+    "*   field required",
+    "=   field inherited",
+];
+
+/*  A cell of a line is a set of the directions it joins; the glyph is
+ *  what those directions draw.  */
+const L = 1, R = 2, U = 4, D = 8;
+const GLYPH = {
+    [L|R]: "─", [L]: "─", [R]: "─",
+    [U|D]: "│", [U]: "│", [D]: "│",
+    [R|D]: "┌", [L|D]: "┐", [R|U]: "└", [L|U]: "┘",
+    [L|R|D]: "┬", [L|R|U]: "┴", [U|D|R]: "├", [U|D|L]: "┤",
+    [L|R|U|D]: "┼",
+};
+
+
+/***************************************************************
+ *  A value that may be one string or a list of them, as a list.
+ ***************************************************************/
+function as_list(value)
+{
+    if(typeof value === "string") {
+        return value ? [value] : [];
+    }
+    if(Array.isArray(value)) {
+        let list = [];
+        for(let v of value) {
+            list.push(...as_list(v));
+        }
+        return list;
+    }
+    if(value && typeof value === "object") {
+        let list = [];
+        for(let v of Object.values(value)) {
+            list.push(...as_list(v));
+        }
+        return list;
+    }
+    return [];
+}
+
+/***************************************************************
+ *  The columns of a topic as [name, desc] in declared order: a
+ *  dict in the literals, a list of {id} in some stores.
+ ***************************************************************/
+function topic_cols(topic)
+{
+    let cols = topic.cols || {};
+    if(Array.isArray(cols)) {
+        return cols.map((c) => [c.id, c]);
+    }
+    return Object.entries(cols);
+}
+
+/***************************************************************
+ *  What a link column looks like at its end of the line.
+ ***************************************************************/
+function hook_marker(type)
+{
+    if(type === "dict" || type === "object") {
+        return "{}";
+    }
+    if(type === "array" || type === "list") {
+        return "[]";
+    }
+    return "()";
+}
+
+function fkey_marker(type)
+{
+    if(type === "dict" || type === "object") {
+        return "{↖}";
+    }
+    if(type === "array" || type === "list") {
+        return "[↖]";
+    }
+    return "(↖)";
+}
+
+/***************************************************************
+ *  One row of a box: the text inside it, and whether it is a
+ *  link column (written against the right edge, where its line
+ *  leaves the box).
+ ***************************************************************/
+function col_row(topic, name, desc, pkey2s)
+{
+    let flags = as_list(desc.flag);
+    if(flags.indexOf("hook") >= 0) {
+        return {text: `${name} ${hook_marker(desc.type)}`, link: true};
+    }
+    if(flags.indexOf("fkey") >= 0) {
+        return {text: `${name} ${fkey_marker(desc.type)}`, link: true};
+    }
+    let mark = flags.indexOf("required") >= 0 ? "*" :
+               flags.indexOf("inherit") >= 0 ? "=" : " ";
+    let text = `${mark} ${name}`;
+    if(pkey2s.indexOf(name) >= 0) {
+        text += " (2)";
+    }
+    if(topic.tkey && topic.tkey === name) {
+        text += " (t)";
+    }
+    return {text: text, link: false};
+}
+
+/***************************************************************
+ *  schema_to_diagram(schema) -> the text, one string with a
+ *  newline per line and no trailing spaces.
+ ***************************************************************/
+function schema_to_diagram(schema)
+{
+    if(!schema || !Array.isArray(schema.topics)) {
+        return "";
+    }
+
+    /*
+     *  The boxes, and where each column landed
+     */
+    let boxes = [];
+    let inner = MIN_INNER;
+    for(let topic of schema.topics) {
+        let pkey2s = as_list(topic.pkey2s);
+        let rows = topic_cols(topic).map(([name, desc]) =>
+            Object.assign({name: name}, col_row(topic, name, desc || {}, pkey2s))
+        );
+        for(let row of rows) {
+            inner = Math.max(inner, row.text.length + 2);
+        }
+        let title = topic.id + (topic.main_topic ? "  (main_topic)" : "");
+        inner = Math.max(inner, title.length);
+        boxes.push({topic: topic, title: title, rows: rows});
+    }
+
+    let lines = [];
+    let where = {};     /*  "topic`col" -> line index  */
+    let edge = INDENT + inner + 1;
+
+    lines.push(`${schema.id || ""}  (schema_version ${schema.schema_version || "?"})`);
+    lines.push("");
+    for(let l of LEGEND) {
+        lines.push(l);
+    }
+    lines.push("");
+    lines.push("");
+
+    for(let box of boxes) {
+        let pad = Math.max(0, Math.floor((inner + 2 - box.title.length) / 2));
+        lines.push(" ".repeat(INDENT + pad) + box.title);
+        lines.push(" ".repeat(INDENT) + "┌" + "─".repeat(inner) + "┐");
+        for(let row of box.rows) {
+            let text = row.link ?
+                row.text.padStart(inner - 1) + " " :
+                row.text.padEnd(inner);
+            where[`${box.topic.id}\`${row.name}`] = lines.length;
+            lines.push(" ".repeat(INDENT) + "│" + text + "│");
+        }
+        lines.push(" ".repeat(INDENT) + "└" + "─".repeat(inner) + "┘");
+        lines.push("");
+    }
+
+    /*
+     *  The links: from a hook's row to the row of the fkey it fills
+     */
+    let links = [];
+    for(let topic of schema.topics) {
+        for(let [name, desc] of topic_cols(topic)) {
+            desc = desc || {};
+            if(as_list(desc.flag).indexOf("hook") < 0) {
+                continue;
+            }
+            let hook = desc.hook;
+            if(!hook || typeof hook !== "object" || Array.isArray(hook)) {
+                continue;
+            }
+            for(let [child_topic, fkey_col] of Object.entries(hook)) {
+                let from = where[`${topic.id}\`${name}`];
+                let to = where[`${child_topic}\`${fkey_col}`];
+                if(from === undefined || to === undefined) {
+                    continue;
+                }
+                links.push({from: from, to: to,
+                            top: Math.min(from, to), bottom: Math.max(from, to)});
+            }
+        }
+    }
+
+    /*  Shorter links nearer the boxes: a lane holds links whose rows
+     *  do not overlap.  */
+    links.sort((a, b) => (a.bottom - a.top) - (b.bottom - b.top) || a.top - b.top);
+    let lanes = [];
+    for(let link of links) {
+        let k = 0;
+        for(;; k++) {
+            let used = lanes[k] || [];
+            let free = used.every((o) => link.bottom < o.top || o.bottom < link.top);
+            if(free) {
+                break;
+            }
+        }
+        lanes[k] = (lanes[k] || []).concat([link]);
+        link.x = edge + LANE_GAP + LANE_GAP * k;
+    }
+
+    /*
+     *  Draw them on a grid of direction bits, then as glyphs
+     */
+    let bits = {};
+    let fixed = {};
+    let join = (y, x, b) => {
+        let key = `${y},${x}`;
+        bits[key] = (bits[key] || 0) | b;
+    };
+    let hline = (y, x1, x2) => {
+        for(let x = x1; x <= x2; x++) {
+            join(y, x, (x > x1 ? L : 0) | (x < x2 ? R : 0));
+        }
+    };
+    let vline = (x, y1, y2) => {
+        for(let y = y1; y <= y2; y++) {
+            join(y, x, (y > y1 ? U : 0) | (y < y2 ? D : 0));
+        }
+    };
+    for(let link of links) {
+        hline(link.from, edge + 2, link.x);
+        hline(link.to, edge + 2, link.x);
+        vline(link.x, link.top, link.bottom);
+        fixed[`${link.from},${edge + 2}`] = "◀";
+    }
+
+    let out = lines.map((line, y) => {
+        let chars = Array.from(line);
+        for(let key of Object.keys(bits)) {
+            let [ky, kx] = key.split(",").map(Number);
+            if(ky !== y) {
+                continue;
+            }
+            while(chars.length <= kx) {
+                chars.push(" ");
+            }
+            chars[kx] = fixed[key] || GLYPH[bits[key]] || " ";
+        }
+        return chars.join("").replace(/\s+$/, "");
+    });
+
+    while(out.length && out[out.length - 1] === "") {
+        out.pop();
+    }
+    return out.join("\n");
+}
+
+
+export {
+    schema_to_diagram,
+};

package/src/schema_to_diagram.test.js

@@ -0,0 +1,107 @@
+/***********************************************************************
+ *          schema_to_diagram.test.js
+ *
+ *      The graph of a schema as text, pinned on a small schema that has
+ *      every case: a self-referent hook, a hook to another topic, one
+ *      hook filling two topics, a pkey2, a tkey, required and inherited
+ *      fields, and the main topic.
+ ***********************************************************************/
+import { describe, test, expect } from "vitest";
+import { schema_to_diagram } from "./schema_to_diagram.js";
+
+
+const SCHEMA = {
+    id: "treedb_sample",
+    schema_version: "4",
+    topics: [
+        {
+            id: "departments",
+            pkey: "id",
+            main_topic: true,
+            cols: {
+                id:             {type: "string", flag: ["persistent", "required"]},
+                departments:    {type: "dict", flag: ["hook"], hook: {departments: "department_id"}},
+                department_id:  {type: "string", flag: ["fkey"]},
+                users:          {type: "dict", flag: ["hook"], hook: {users: "departments"}},
+                managers:       {type: "list", flag: ["hook"],
+                                 hook: {users: "manager", departments: "manager"}},
+                manager:        {type: "array", flag: ["fkey"]},
+            }
+        },
+        {
+            id: "users",
+            pkey: "id",
+            pkey2s: "name",
+            tkey: "tm",
+            cols: {
+                id:             {type: "string", flag: "required"},
+                name:           {type: "string", flag: ["persistent"]},
+                enabled:        {type: "boolean", flag: ["persistent", "inherit"]},
+                tm:             {type: "integer", flag: ["time"]},
+                departments:    {type: "array", flag: ["fkey"]},
+                manager:        {type: "array", flag: ["fkey"]},
+            }
+        },
+    ]
+};
+
+const EXPECTED = `treedb_sample  (schema_version 4)
+
+{}  dict hook   (N unique children)
+[]  list hook   (n not-unique children)
+()  string hook (1 unique child)
+(↖) 1 fkey      (1 parent)
+[↖] n fkeys     (n parents)
+{↖} N fkeys     (N parents)
+
+(2) pkey2 - secondary key
+(t) tkey  - time key
+*   field required
+=   field inherited
+
+
+          departments  (main_topic)
+        ┌───────────────────────────┐
+        │* id                       │
+        │            departments {} │ ◀─┐
+        │         department_id (↖) │ ──┘
+        │                  users {} │ ◀─────┐
+        │               managers [] │ ◀─┬───┼───┐
+        │               manager [↖] │ ──┘   │   │
+        └───────────────────────────┘       │   │
+                                            │   │
+                    users                   │   │
+        ┌───────────────────────────┐       │   │
+        │* id                       │       │   │
+        │  name (2)                 │       │   │
+        │= enabled                  │       │   │
+        │  tm (t)                   │       │   │
+        │           departments [↖] │ ──────┘   │
+        │               manager [↖] │ ──────────┘
+        └───────────────────────────┘`;
+
+
+describe("schema_to_diagram", () => {
+    const diagram = schema_to_diagram(SCHEMA);
+
+    test("the whole picture", () => {
+        expect(diagram).toBe(EXPECTED);
+    });
+
+    test("no line ends in a space", () => {
+        for(const line of diagram.split("\n")) {
+            expect(line).toBe(line.trimEnd());
+        }
+    });
+
+    test("a link to a column that does not exist is not drawn", () => {
+        const broken = JSON.parse(JSON.stringify(SCHEMA));
+        broken.topics[0].cols.users.hook = {users: "nowhere"};
+        expect(schema_to_diagram(broken)).not.toContain("◀─────┐");
+    });
+
+    test("nothing to draw is an empty string, not a throw", () => {
+        expect(schema_to_diagram(null)).toBe("");
+        expect(schema_to_diagram({id: "x"})).toBe("");
+    });
+});

package/src/schema_validate.js

@@ -16,10 +16,11 @@
  *                  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.
+ *                  like.
+ *
+ *      A version is not checked here: an edit is a DRAFT and moves no
+ *      version, and C_TREEDB's save-schema raises the versions of what
+ *      changed when it publishes it.
  *
  *      Every `code` is an i18n key: the caller renders, this decides.
  *
@@ -69,8 +70,6 @@ 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;
@@ -117,17 +116,6 @@ function validate_schema(treedb, options)
             }
         }
 
-        /*  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 : "";

package/src/schema_validate.test.js

@@ -221,34 +221,14 @@ describe("the column itself", () => {
     });
 });
 
-describe("the version that did not move", () => {
-    test("a written topic whose topic_version is unchanged is reported", () => {
+describe("a version is not the validator's", () => {
+    test("a written topic whose topic_version did not move is NOT reported", () => {
+        /*  An edit is a draft; save-schema raises the version.  */
         const f = validate_schema(schema(), {
             written_topics: ["db.departments"],
             baseline: {"db.departments": 1}
         });
-        const v = f.filter(x => x.code === "topic version not bumped");
-        expect(v.length).toBe(1);
-        expect(v[0].topic).toBe("departments");
-        expect(v[0].severity).toBe("warning");
-    });
-
-    test("a bumped version says nothing", () => {
-        expect(validate_schema(schema({dep_version: 2}), {
-            written_topics: ["db.departments"],
-            baseline: {"db.departments": 1}
-        })).toEqual([]);
-    });
-
-    test("a topic nobody wrote is not asked about its version", () => {
-        expect(validate_schema(schema(), {baseline: {"db.departments": 1}})).toEqual([]);
-    });
-
-    test("a version compared across types still matches (2 vs '2')", () => {
-        expect(validate_schema(schema({dep_version: "1"}), {
-            written_topics: ["db.departments"],
-            baseline: {"db.departments": 1}
-        }).length).toBe(1);
+        expect(f.filter(x => x.code === "topic version not bumped")).toEqual([]);
     });
 });
 

package/src/schema_version_bump.test.js

@@ -1,92 +1,35 @@
 /***********************************************************************
  *          schema_version_bump.test.js
  *
- *      "This topic was written and its version did not move."
+ *      "This topic was written in this session and is not saved."
  *
- *      THE RULE MEASURES AGAINST A BASELINE, AND THE BASELINE MUST NOT
- *      MOVE WITH IT.  It used to be re-taken inside build_model(), which
- *      runs again on the patch after EVERY write -- so it came back as
- *      the version the write had just raised, the rule read TRUE for a
- *      topic whose version HAD moved, and the banner that says so
- *      offered a Raise button that wrote another version and was
- *      measured against itself again.
- *
- *      The banner could not be dismissed.  One operator pressed it
- *      thirty-three times on a single column delete, and that is why
- *      schema versions climbed by tens with the schema unchanged.
+ *      An edit is a DRAFT (M36 of yunetas' 2026-09-21 review): it moves
+ *      no version, and the host's save-schema raises the versions of what
+ *      changed. So "written" alone is the whole question -- the version is
+ *      no longer measured against a baseline, which is also why the old
+ *      "Raise" button and the loop it fed are gone.
  *
  *          Copyright (c) 2026, ArtGins.
  *          All Rights Reserved.
  ***********************************************************************/
 import {describe, it, expect} from "vitest";
-import {needs_version_bump} from "./c_yui_schema_editor.js";
+import {topic_is_draft} from "./c_yui_schema_editor.js";
 
 const TOPIC = {id: "device_groups", topic_version: 5};
 
-describe("needs_version_bump", () => {
+describe("topic_is_draft", () => {
     it("says nothing about a topic this session never wrote", () => {
-        expect(needs_version_bump({}, {device_groups: 5}, TOPIC)).toBe(false);
+        expect(topic_is_draft({}, TOPIC)).toBe(false);
     });
 
-    it("asks for the bump when the version sits where it was found", () => {
-        expect(needs_version_bump({device_groups: true}, {device_groups: 5}, TOPIC))
+    it("a written topic is a draft, whatever its version says", () => {
+        expect(topic_is_draft({device_groups: true}, TOPIC)).toBe(true);
+        expect(topic_is_draft({device_groups: true}, {id: "device_groups", topic_version: 6}))
             .toBe(true);
     });
 
-    it("STOPS asking once the version has moved past the baseline", () => {
-        /*  The case the loop got wrong: the write raised it to 6 and the
-         *  baseline still says 5, so there is nothing left to raise.  */
-        expect(needs_version_bump(
-            {device_groups: true}, {device_groups: 5}, {id: "device_groups", topic_version: 6}
-        )).toBe(false);
-    });
-
-    it("compares as text, so 5 and '5' are the same version", () => {
-        expect(needs_version_bump(
-            {device_groups: true}, {device_groups: "5"}, TOPIC
-        )).toBe(true);
-        expect(needs_version_bump(
-            {device_groups: true}, {device_groups: 5}, {id: "device_groups", topic_version: "5"}
-        )).toBe(true);
-    });
-
     it("answers false rather than throwing on a missing half", () => {
-        expect(needs_version_bump(null, {device_groups: 5}, TOPIC)).toBe(false);
-        expect(needs_version_bump({device_groups: true}, null, TOPIC)).toBe(false);
-        expect(needs_version_bump({device_groups: true}, {device_groups: 5}, null)).toBe(false);
-    });
-
-    it("a topic with no baseline entry is not owed a bump", () => {
-        expect(needs_version_bump({device_groups: true}, {}, TOPIC)).toBe(false);
-    });
-});
-
-describe("the loop it came from", () => {
-    /*
-     *  What the editor does per bump: raise the version by one. With the
-     *  baseline left alone, ONE press settles it; with the baseline
-     *  re-taken each time -- the old bug -- it never settles.
-     */
-    function press_raise(state) {
-        return {written: state.written, baseline: state.baseline,
-                topic: {id: "t", topic_version: Number(state.topic.topic_version) + 1}};
-    }
-
-    it("settles after a single press", () => {
-        let st = {written: {t: true}, baseline: {t: 5}, topic: {id: "t", topic_version: 5}};
-        expect(needs_version_bump(st.written, st.baseline, st.topic)).toBe(true);
-        st = press_raise(st);
-        expect(needs_version_bump(st.written, st.baseline, st.topic)).toBe(false);
-    });
-
-    it("never settles if the baseline is re-taken with the version", () => {
-        let st = {written: {t: true}, baseline: {t: 5}, topic: {id: "t", topic_version: 5}};
-        let presses = 0;
-        while(needs_version_bump(st.written, st.baseline, st.topic) && presses < 40) {
-            st = press_raise(st);
-            st.baseline = {t: st.topic.topic_version};   /*  the bug  */
-            presses++;
-        }
-        expect(presses).toBe(40);       /*  it ran to the guard: no way out  */
+        expect(topic_is_draft(null, TOPIC)).toBe(false);
+        expect(topic_is_draft({device_groups: true}, null)).toBe(false);
     });
 });