@cloudcrane/app-spec 0.4.0 → 0.7.0

package/dist/src/schema.js

@@ -61,6 +61,8 @@ export const CodedComponent = z
     kind: z.literal("coded"),
     /** game: a canvas, a loop and touch, the code a script; page: a whole HTML page, drawn full screen (what an app written as HTML becomes). */
     kit: z.enum(["game", "page"]),
+    /** Optional: the native widget or screen it stands in for, like "CupertinoSlidingSegmentedControl", so `blackbox coverage` can say which the catalog lacks. */
+    replaces: Text(120).optional(),
     inputs: z.record(CelName, CodedType).default({}),
     events: z.record(CelName, z.record(CelName, CodedType)).default({}),
     code: z
@@ -80,6 +82,8 @@ export const CodedComponent = z
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["code"], message: "a game kit's code is at most 64 KB" });
 })
     .refine((c) => Object.keys(c.inputs).length <= 10 && Object.keys(c.events).length <= 10, "at most 10 inputs and 10 events");
+/** The kinds of thing a ported app may not do that its original did. */
+export const GAP_KINDS = ["background", "widget", "notifications", "purchases", "accounts", "sync", "device", "other"];
 export const SpecSchema = z
     .object({
     v: z.literal(1),
@@ -138,6 +142,11 @@ export const SpecSchema = z
             .default([]),
         /** Each step turns version `from` into `to`, as a CEL expression over `saved`. */
         migrations: z.array(z.object({ from: z.number().int().min(1), to: z.number().int().min(2), cel: Cel }).strict()),
+        /**
+         * What it keeps: the saved fields that are personal (health, money, people's names), as pointers into the saved
+         * data, like /days or /people. They stay on the phone; CloudCrane never puts them in a remix, screenshot or report.
+         */
+        personal: z.array(Pointer).max(20).optional(),
     })
         .strict(),
     logic: z
@@ -147,11 +156,21 @@ export const SpecSchema = z
         /** Values the screens read, kept up to date: a data-model pointer and the CEL that computes it. */
         computed: z.record(Pointer, Cel).default({}),
         /** Examples each function must reproduce: recorded from the source's own tests, or given. */
-        vectors: z.array(z.object({ fn: CelName, in: z.array(z.unknown()).max(8), out: z.unknown(), from: z.enum(["recorded", "hint"]) }).strict()).default([]),
+        /**
+         * Examples each function must reproduce: `recorded` from the module's own tests, `app` from calls recorded while
+         * the original app ran, `hint` written by hand.
+         */
+        vectors: z
+            .array(z.object({ fn: CelName, in: z.array(z.unknown()).max(8), out: z.unknown(), from: z.enum(["recorded", "app", "hint"]) }).strict())
+            .default([]),
     })
         .strict(),
+    /**
+     * What it can reach: each site, why, and what it's sent, in the person's words ("the city you typed"). Shown to the
+     * person before the app opens; a site the code names but this doesn't list is refused.
+     */
     network: z
-        .array(z.object({ site: z.string().regex(/^[a-z0-9.-]+\.[a-z]{2,}$/), why: Text(300) }).strict())
+        .array(z.object({ site: z.string().regex(/^[a-z0-9.-]+\.[a-z]{2,}$/), why: Text(300), sends: Text(200) }).strict())
         .max(5)
         .default([]),
     /** The device features the app uses, by CloudCrane's names, each once with why; anything not listed is blocked. */
@@ -159,6 +178,29 @@ export const SpecSchema = z
         .array(z.object({ what: z.enum(USE_NAMES), why: Text(300) }).strict())
         .max(USE_NAMES.length)
         .default([]),
+    /**
+     * What it does: each screen in words, and what it shows when there's nothing yet, while it loads, offline, and when
+     * something fails. Optional; without it the blueprint describes the one surface from its words.
+     */
+    screens: z
+        .array(z
+        .object({
+        id: Id,
+        says: Text(300),
+        states: z
+            .object({ empty: Text(200).optional(), loading: Text(200).optional(), offline: Text(200).optional(), error: Text(200).optional() })
+            .strict()
+            .optional(),
+    })
+        .strict())
+        .min(1)
+        .max(20)
+        .optional(),
+    /** How it looks on the phone: the orientation it holds and whether it fills the screen (Android honours both). */
+    screen: z
+        .object({ orientation: z.enum(["portrait", "landscape", "any"]).optional(), fullscreen: z.boolean().optional() })
+        .strict()
+        .optional(),
     journeys: z
         .array(z
         .object({
@@ -176,6 +218,16 @@ export const SpecSchema = z
         .record(Id, CodedComponent)
         .refine((c) => Object.keys(c).length <= 5, "at most 5 components")
         .default({}),
+    /** The page-kit component that is the whole app: the spec is then that page, compiled to its HTML as written (see page.ts). */
+    page: Id.optional(),
+    /**
+     * What the original app does that this one doesn't, said plainly so no one is promised it: a native feature with
+     * no web equivalent yet (background jobs, home-screen widgets, push notifications, in-app purchases...).
+     */
+    gaps: z
+        .array(z.object({ kind: z.enum(GAP_KINDS), what: Text(120), why: Text(300).optional() }).strict())
+        .max(20)
+        .optional(),
     /** What a remix may change and what stays as the partner made it. */
     mods: z
         .object({ open: z.array(PointerPattern), locked: z.array(PointerPattern) })

package/dist/src/validate.d.ts

@@ -3,4 +3,5 @@ import { type Spec } from "./schema.js";
 export declare function validateSpec(input: unknown, catalog?: Catalog): {
     spec: Spec | null;
     problems: Problem[];
+    warnings: Problem[];
 };

package/dist/src/validate.js

@@ -3,8 +3,15 @@ import { catalogFor } from "./catalog.js";
 import { leakProblems } from "./leak.js";
 import { logicProblems } from "./logic.js";
 import { SpecSchema } from "./schema.js";
+import { pageProblems } from "./page.js";
+import { designWarnings, statesWarnings } from "./design.js";
+import { memoryProblems } from "./memory.js";
+import { reachProblems } from "./reach.js";
+import { rulesWarnings } from "./fidelity.js";
 // Everything wrong with a spec, collected rather than stopping at the first: the
-// envelope's shape, then the A2UI surface, then references between parts.
+// envelope's shape, then the A2UI surface, then references between parts, what it keeps (memory.ts) and what its code
+// reaches (reach.ts). Problems refuse it. Warnings (how it looks and what each screen shows when empty, offline or
+// failing: design.ts) don't: they say what would make it better.
 const pathOf = (path) => path
     .map((p) => (typeof p === "number" ? `[${p}]` : `.${p}`))
     .join("")
@@ -12,12 +19,12 @@ const pathOf = (path) => path
 export function validateSpec(input, catalog) {
     const parsed = SpecSchema.safeParse(input);
     if (!parsed.success)
-        return { spec: null, problems: parsed.error.issues.map((i) => ({ at: pathOf(i.path) || "spec", problem: i.message })) };
+        return { spec: null, problems: parsed.error.issues.map((i) => ({ at: pathOf(i.path) || "spec", problem: i.message })), warnings: [] };
     const spec = parsed.data;
     // The surface is checked against the catalog it names (CloudCrane's, or A2UI's basic one).
     const named = catalog ?? catalogFor(spec.surface.catalog);
     if (!named)
-        return { spec: null, problems: [{ at: "surface.catalog", problem: "not a catalog this runtime has" }] };
+        return { spec: null, problems: [{ at: "surface.catalog", problem: "not a catalog this runtime has" }], warnings: [] };
     const problems = [...surfaceProblems(spec.surface.messages, named)];
     const catalogId = spec.surface.messages[0].createSurface?.catalogId;
     if (catalogId && catalogId !== spec.surface.catalog)
@@ -46,11 +53,12 @@ export function validateSpec(input, catalog) {
     for (const m of spec.data.migrations)
         if (m.to !== m.from + 1 || m.to > spec.data.version)
             problems.push({ at: `data.migrations ${m.from}`, problem: "steps go one version at a time, up to data.version" });
-    problems.push(...codedProblems(spec), ...logicProblems(spec), ...leakProblems(spec));
+    problems.push(...codedProblems(spec), ...pageProblems(spec), ...logicProblems(spec), ...leakProblems(spec), ...memoryProblems(spec), ...reachProblems(spec));
     for (const locked of spec.mods.locked)
         if (spec.mods.open.includes(locked))
             problems.push({ at: `mods ${locked}`, problem: "both open and locked" });
-    return { spec: problems.length ? null : spec, problems };
+    const warnings = [...designWarnings(spec), ...statesWarnings(spec), ...rulesWarnings(spec)];
+    return { spec: problems.length ? null : spec, problems, warnings };
 }
 /** Each Coded placement names a component the spec defines, and only its declared inputs and events; each component is placed. */
 function codedProblems(spec) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcrane/app-spec",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "The CloudCrane app spec: its schema, the expression language its rules are written in, and the checks that keep partner code out of it.",
   "keywords": [
     "cloudcrane",

package/schema/app-spec.v1.json

@@ -204,6 +204,14 @@
             ],
             "additionalProperties": false
           }
+        },
+        "personal": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(\\/([^~/]|~[01])*)*$"
+          },
+          "maxItems": 20
         }
       },
       "required": [
@@ -293,6 +301,7 @@
                 "type": "string",
                 "enum": [
                   "recorded",
+                  "app",
                   "hint"
                 ]
               }
@@ -322,11 +331,17 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 300
+          },
+          "sends": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
           }
         },
         "required": [
           "site",
-          "why"
+          "why",
+          "sends"
         ],
         "additionalProperties": false
       },
@@ -367,6 +382,73 @@
       "maxItems": 9,
       "default": []
     },
+    "screens": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-zA-Z0-9_.-]{0,63}$"
+          },
+          "says": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300
+          },
+          "states": {
+            "type": "object",
+            "properties": {
+              "empty": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200
+              },
+              "loading": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200
+              },
+              "offline": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200
+              },
+              "error": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "id",
+          "says"
+        ],
+        "additionalProperties": false
+      },
+      "minItems": 1,
+      "maxItems": 20
+    },
+    "screen": {
+      "type": "object",
+      "properties": {
+        "orientation": {
+          "type": "string",
+          "enum": [
+            "portrait",
+            "landscape",
+            "any"
+          ]
+        },
+        "fullscreen": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
     "journeys": {
       "type": "array",
       "items": {
@@ -466,6 +548,11 @@
               "page"
             ]
           },
+          "replaces": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120
+          },
           "inputs": {
             "type": "object",
             "additionalProperties": {
@@ -524,6 +611,47 @@
       },
       "default": {}
     },
+    "page": {
+      "type": "string",
+      "pattern": "^[a-z][a-zA-Z0-9_.-]{0,63}$"
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "background",
+              "widget",
+              "notifications",
+              "purchases",
+              "accounts",
+              "sync",
+              "device",
+              "other"
+            ]
+          },
+          "what": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120
+          },
+          "why": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300
+          }
+        },
+        "required": [
+          "kind",
+          "what"
+        ],
+        "additionalProperties": false
+      },
+      "maxItems": 20
+    },
     "mods": {
       "type": "object",
       "properties": {