@cloudcrane/app-spec 0.0.0-stage → 0.1.0

package/dist/src/logic.js

@@ -0,0 +1,197 @@
+import { Environment } from "@marcbachmann/cel-js";
+import { canonical } from "./canonical.js";
+export const MAX_RANGE = 3660;
+const MAX_DEPTH = 64;
+const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** JSON in: whole numbers become CEL ints (BigInt). */
+export function toCel(v) {
+    if (typeof v === "number" && Number.isInteger(v))
+        return BigInt(v);
+    if (Array.isArray(v))
+        return v.map(toCel);
+    if (v && typeof v === "object")
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, toCel(x)]));
+    return v;
+}
+/** CEL out: ints become numbers again, so results are plain JSON. */
+export function fromCel(v) {
+    if (typeof v === "bigint")
+        return Number(v);
+    if (Array.isArray(v))
+        return v.map(fromCel);
+    if (v instanceof Map)
+        return Object.fromEntries([...v].map(([k, x]) => [String(k), fromCel(x)]));
+    if (v && typeof v === "object")
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, fromCel(x)]));
+    return v;
+}
+/** Whole days since 1970-01-01 for a real "YYYY-MM-DD", in UTC so no clock or zone can move it. */
+function dayNumber(s) {
+    const m = DAY.exec(s);
+    if (!m)
+        throw new Error(`not a day: ${s}`);
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const t = Date.UTC(y, mo - 1, d);
+    const back = new Date(t);
+    if (back.getUTCFullYear() !== y || back.getUTCMonth() !== mo - 1 || back.getUTCDate() !== d)
+        throw new Error(`not a day: ${s}`);
+    return t / 86_400_000;
+}
+const dayString = (n) => new Date(n * 86_400_000).toISOString().slice(0, 10);
+export const dates = {
+    addDays: (s, n) => dayString(dayNumber(s) + Number(n)),
+    daysBetween: (a, b) => BigInt(dayNumber(b) - dayNumber(a)),
+    /** The Monday that starts s's week. */
+    weekStart: (s) => {
+        const n = dayNumber(s);
+        return dayString(n - ((new Date(n * 86_400_000).getUTCDay() + 6) % 7));
+    },
+    dateRange: (a, b) => {
+        const [from, to] = [dayNumber(a), dayNumber(b)];
+        if (to - from > MAX_RANGE)
+            throw new Error(`a range of at most ${MAX_RANGE} days`);
+        const out = [];
+        for (let n = from; n < to; n++)
+            out.push(dayString(n));
+        return out;
+    },
+};
+/** Function names a CEL expression calls, by name or as a fold step ("name"). */
+function callsIn(cel, names) {
+    const out = new Set();
+    for (const m of cel.matchAll(/([A-Za-z_][A-Za-z0-9_]*)\s*\(/g))
+        if (names.has(m[1]))
+            out.add(m[1]);
+    for (const m of cel.matchAll(/(["'])([A-Za-z_][A-Za-z0-9_]*)\1/g))
+        if (names.has(m[2]))
+            out.add(m[2]);
+    return [...out];
+}
+/** A cycle among the spec's functions, as names, or null. */
+export function cycleIn(functions) {
+    const names = new Set(Object.keys(functions));
+    const edges = new Map([...names].map((n) => [n, callsIn(functions[n].cel, names)]));
+    const state = new Map();
+    const walk = (n, path) => {
+        if (state.get(n) === "open")
+            return [...path.slice(path.indexOf(n)), n];
+        if (state.get(n) === "done")
+            return null;
+        state.set(n, "open");
+        for (const m of edges.get(n) ?? []) {
+            const found = walk(m, [...path, n]);
+            if (found)
+                return found;
+        }
+        state.set(n, "done");
+        return null;
+    };
+    for (const n of names) {
+        const found = walk(n, []);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** The rules of one spec, ready to evaluate. */
+export class Rules {
+    logic;
+    env;
+    consts;
+    depth = 0;
+    constructor(logic) {
+        this.logic = logic;
+        this.consts = toCel(logic.consts);
+        const env = new Environment({ unlistedVariablesAreDyn: true, homogeneousAggregateLiterals: false });
+        env.registerFunction("addDays(string, int): string", dates.addDays);
+        env.registerFunction("daysBetween(string, string): int", dates.daysBetween);
+        env.registerFunction("weekStart(string): string", dates.weekStart);
+        env.registerFunction("dateRange(string, string): list<string>", dates.dateRange);
+        env.registerFunction("list.sort(): list", (list) => [...list].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)));
+        env.registerFunction("fold(list, dyn, string): dyn", (list, init, step) => {
+            if (!(step in logic.functions))
+                throw new Error(`fold: no function ${step}`);
+            return list.reduce((acc, item) => this.call(step, [acc, item]), init);
+        });
+        for (const [name, fn] of Object.entries(logic.functions)) {
+            env.registerFunction(`${name}(${fn.params.map(() => "dyn").join(", ")}): dyn`, (...args) => this.call(name, args));
+        }
+        this.env = env;
+    }
+    call(name, args) {
+        const fn = this.logic.functions[name];
+        if (++this.depth > MAX_DEPTH) {
+            this.depth = 0;
+            throw new Error("calls nest too deep");
+        }
+        try {
+            return this.env.evaluate(fn.cel, { ...this.consts, ...Object.fromEntries(fn.params.map((p, i) => [p, args[i] ?? null])) });
+        }
+        finally {
+            this.depth--;
+        }
+    }
+    /** An expression's value, as JSON; null when it can't be worked out. */
+    evaluate(cel, vars = {}) {
+        try {
+            this.depth = 0;
+            return fromCel(this.env.evaluate(cel, { ...this.consts, ...toCel(vars) }));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** A spec function applied to JSON arguments; null when it can't be worked out. */
+    apply(name, args) {
+        try {
+            this.depth = 0;
+            return fromCel(this.call(name, args.map(toCel)));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Why an expression won't parse, or null when it does. */
+    parseError(cel) {
+        try {
+            this.env.parse(cel);
+            return null;
+        }
+        catch (e) {
+            return e.message.split("\n")[0] ?? "doesn't parse";
+        }
+    }
+}
+/** Equal as JSON values, whatever the key order (RFC 8785 canonical form). */
+const same = (a, b) => canonical(a ?? null) === canonical(b ?? null);
+/** A key as one JSON Pointer token (RFC 6901). */
+const token = (k) => k.replace(/~/g, "~0").replace(/\//g, "~1");
+/** Problems with a spec's rules, each at its JSON Pointer: expressions that don't parse, a call cycle, vectors the rules don't reproduce. */
+export function logicProblems(spec) {
+    const problems = [];
+    const cycle = cycleIn(spec.logic.functions);
+    if (cycle)
+        return [{ at: "/logic/functions", problem: `functions call each other in a cycle: ${cycle.join(" → ")}` }];
+    const rules = new Rules(spec.logic);
+    const each = [
+        ...Object.entries(spec.logic.functions).map(([n, f]) => [`/logic/functions/${token(n)}/cel`, f.cel]),
+        ...Object.entries(spec.logic.computed).map(([p, cel]) => [`/logic/computed/${token(p)}`, cel]),
+        ...spec.data.migrations.map((m, i) => [`/data/migrations/${i}/cel`, m.cel]),
+    ];
+    for (const [at, cel] of each) {
+        const why = rules.parseError(cel);
+        if (why)
+            problems.push({ at, problem: `doesn't parse: ${why}` });
+    }
+    if (problems.length)
+        return problems;
+    spec.logic.vectors.forEach((v, i) => {
+        const got = rules.apply(v.fn, v.in);
+        if (!same(got, v.out))
+            problems.push({
+                at: `/logic/vectors/${i}`,
+                problem: `${v.fn}(${JSON.stringify(v.in).slice(1, -1)}) gives ${JSON.stringify(got)}, not ${JSON.stringify(v.out)}`,
+            });
+    });
+    return problems;
+}

package/dist/src/schema.d.ts

@@ -0,0 +1,418 @@
+import { z } from "zod";
+/** A neutral id: lower-case words, dots, dashes, underscores. Partner symbol names live only in provenance. */
+export declare const Id: z.ZodString;
+/** A CEL identifier (constants and parameters): letters, digits and underscores. */
+export declare const CelName: z.ZodString;
+/** An RFC 6901 JSON Pointer. */
+export declare const Pointer: z.ZodString;
+/** A pointer, or a pointer ending in /* for everything under it (mod points). */
+export declare const PointerPattern: z.ZodString;
+export type TokenNode = {
+    $value?: unknown;
+    $type?: string;
+    $description?: string;
+    [name: string]: unknown;
+};
+export declare const Tokens: z.ZodType<TokenNode>;
+export declare const SpecSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    manifest: z.ZodObject<{
+        runtime: z.ZodString;
+        generator: z.ZodString;
+        source: z.ZodObject<{
+            fingerprint: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            fingerprint: string;
+        }, {
+            fingerprint: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        runtime: string;
+        generator: string;
+        source: {
+            fingerprint: string;
+        };
+    }, {
+        runtime: string;
+        generator: string;
+        source: {
+            fingerprint: string;
+        };
+    }>;
+    module: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        purpose: z.ZodString;
+        /** How CloudCrane lists it: one of its icon names, its category, up to five tags (CloudCrane checks them). */
+        icon: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        id: string;
+        purpose: string;
+        icon?: string | undefined;
+        category?: string | undefined;
+        tags?: string[] | undefined;
+    }, {
+        name: string;
+        id: string;
+        purpose: string;
+        icon?: string | undefined;
+        category?: string | undefined;
+        tags?: string[] | undefined;
+    }>;
+    tokens: z.ZodType<TokenNode, z.ZodTypeDef, TokenNode>;
+    /** A2UI v0.9.1 messages, the way A2UI's own samples hold them; checked by surfaceProblems. */
+    surface: z.ZodObject<{
+        catalog: z.ZodString;
+        messages: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        catalog: string;
+        messages: Record<string, unknown>[];
+    }, {
+        catalog: string;
+        messages: Record<string, unknown>[];
+    }>;
+    data: z.ZodObject<{
+        version: z.ZodNumber;
+        /** Where it's saved on the phone. */
+        key: z.ZodString;
+        /** The part of the A2UI data model that's saved; the rest is screen state. */
+        persist: z.ZodString;
+        /** JSON Schema of the saved data. */
+        schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        initial: z.ZodUnknown;
+        /**
+         * Two-way views: the runtime keeps `path` equal to the data at `source` (a
+         * pointer with A2UI's ${/path} interpolation, like /saved/days/${/ui/selected}),
+         * and writes edits made through the view back there. For lists a screen shows
+         * by a choice the person makes, since A2UI templates take a fixed path.
+         */
+        views: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            source: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            path: string;
+            source: string;
+        }, {
+            path: string;
+            source: string;
+        }>, "many">>;
+        /** Each step turns version `from` into `to`, as a CEL expression over `saved`. */
+        migrations: z.ZodArray<z.ZodObject<{
+            from: z.ZodNumber;
+            to: z.ZodNumber;
+            cel: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            from: number;
+            to: number;
+            cel: string;
+        }, {
+            from: number;
+            to: number;
+            cel: string;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        version: number;
+        key: string;
+        persist: string;
+        schema: Record<string, unknown>;
+        views: {
+            path: string;
+            source: string;
+        }[];
+        migrations: {
+            from: number;
+            to: number;
+            cel: string;
+        }[];
+        initial?: unknown;
+    }, {
+        version: number;
+        key: string;
+        persist: string;
+        schema: Record<string, unknown>;
+        migrations: {
+            from: number;
+            to: number;
+            cel: string;
+        }[];
+        initial?: unknown;
+        views?: {
+            path: string;
+            source: string;
+        }[] | undefined;
+    }>;
+    logic: z.ZodObject<{
+        consts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean]>>>;
+        functions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            params: z.ZodArray<z.ZodString, "many">;
+            cel: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            params: string[];
+            cel: string;
+        }, {
+            params: string[];
+            cel: string;
+        }>>>;
+        /** Values the screens read, kept up to date: a data-model pointer and the CEL that computes it. */
+        computed: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Examples each function must reproduce: recorded from the source's own tests, or given. */
+        vectors: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            fn: z.ZodString;
+            in: z.ZodArray<z.ZodUnknown, "many">;
+            out: z.ZodUnknown;
+            from: z.ZodEnum<["recorded", "hint"]>;
+        }, "strict", z.ZodTypeAny, {
+            from: "recorded" | "hint";
+            fn: string;
+            in: unknown[];
+            out?: unknown;
+        }, {
+            from: "recorded" | "hint";
+            fn: string;
+            in: unknown[];
+            out?: unknown;
+        }>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        consts: Record<string, string | number | boolean>;
+        functions: Record<string, {
+            params: string[];
+            cel: string;
+        }>;
+        computed: Record<string, string>;
+        vectors: {
+            from: "recorded" | "hint";
+            fn: string;
+            in: unknown[];
+            out?: unknown;
+        }[];
+    }, {
+        consts?: Record<string, string | number | boolean> | undefined;
+        functions?: Record<string, {
+            params: string[];
+            cel: string;
+        }> | undefined;
+        computed?: Record<string, string> | undefined;
+        vectors?: {
+            from: "recorded" | "hint";
+            fn: string;
+            in: unknown[];
+            out?: unknown;
+        }[] | undefined;
+    }>;
+    network: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        site: z.ZodString;
+        why: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        site: string;
+        why: string;
+    }, {
+        site: string;
+        why: string;
+    }>, "many">>;
+    journeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        steps: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            text: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            text: string;
+            id: string;
+        }, {
+            text: string;
+            id: string;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        id: string;
+        steps: {
+            text: string;
+            id: string;
+        }[];
+    }, {
+        title: string;
+        id: string;
+        steps: {
+            text: string;
+            id: string;
+        }[];
+    }>, "many">;
+    promises: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        kind: z.ZodOptional<z.ZodLiteral<"data">>;
+    }, "strict", z.ZodTypeAny, {
+        text: string;
+        id: string;
+        kind?: "data" | undefined;
+    }, {
+        text: string;
+        id: string;
+        kind?: "data" | undefined;
+    }>, "many">>;
+    /** CloudCrane's test steps, as its blueprint tests take them; CloudCrane checks their shape. */
+    tests: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+    /** What a remix may change and what stays as the partner made it. */
+    mods: z.ZodDefault<z.ZodObject<{
+        open: z.ZodArray<z.ZodString, "many">;
+        locked: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        open: string[];
+        locked: string[];
+    }, {
+        open: string[];
+        locked: string[];
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    surface: {
+        catalog: string;
+        messages: Record<string, unknown>[];
+    };
+    v: 1;
+    manifest: {
+        runtime: string;
+        generator: string;
+        source: {
+            fingerprint: string;
+        };
+    };
+    module: {
+        name: string;
+        id: string;
+        purpose: string;
+        icon?: string | undefined;
+        category?: string | undefined;
+        tags?: string[] | undefined;
+    };
+    tokens: TokenNode;
+    data: {
+        version: number;
+        key: string;
+        persist: string;
+        schema: Record<string, unknown>;
+        views: {
+            path: string;
+            source: string;
+        }[];
+        migrations: {
+            from: number;
+            to: number;
+            cel: string;
+        }[];
+        initial?: unknown;
+    };
+    logic: {
+        consts: Record<string, string | number | boolean>;
+        functions: Record<string, {
+            params: string[];
+            cel: string;
+        }>;
+        computed: Record<string, string>;
+        vectors: {
+            from: "recorded" | "hint";
+            fn: string;
+            in: unknown[];
+            out?: unknown;
+        }[];
+    };
+    network: {
+        site: string;
+        why: string;
+    }[];
+    journeys: {
+        title: string;
+        id: string;
+        steps: {
+            text: string;
+            id: string;
+        }[];
+    }[];
+    promises: {
+        text: string;
+        id: string;
+        kind?: "data" | undefined;
+    }[];
+    tests: Record<string, unknown>[];
+    mods: {
+        open: string[];
+        locked: string[];
+    };
+}, {
+    surface: {
+        catalog: string;
+        messages: Record<string, unknown>[];
+    };
+    v: 1;
+    manifest: {
+        runtime: string;
+        generator: string;
+        source: {
+            fingerprint: string;
+        };
+    };
+    module: {
+        name: string;
+        id: string;
+        purpose: string;
+        icon?: string | undefined;
+        category?: string | undefined;
+        tags?: string[] | undefined;
+    };
+    tokens: TokenNode;
+    data: {
+        version: number;
+        key: string;
+        persist: string;
+        schema: Record<string, unknown>;
+        migrations: {
+            from: number;
+            to: number;
+            cel: string;
+        }[];
+        initial?: unknown;
+        views?: {
+            path: string;
+            source: string;
+        }[] | undefined;
+    };
+    logic: {
+        consts?: Record<string, string | number | boolean> | undefined;
+        functions?: Record<string, {
+            params: string[];
+            cel: string;
+        }> | undefined;
+        computed?: Record<string, string> | undefined;
+        vectors?: {
+            from: "recorded" | "hint";
+            fn: string;
+            in: unknown[];
+            out?: unknown;
+        }[] | undefined;
+    };
+    journeys: {
+        title: string;
+        id: string;
+        steps: {
+            text: string;
+            id: string;
+        }[];
+    }[];
+    network?: {
+        site: string;
+        why: string;
+    }[] | undefined;
+    promises?: {
+        text: string;
+        id: string;
+        kind?: "data" | undefined;
+    }[] | undefined;
+    tests?: Record<string, unknown>[] | undefined;
+    mods?: {
+        open: string[];
+        locked: string[];
+    } | undefined;
+}>;
+export type Spec = z.infer<typeof SpecSchema>;