@cloudcrane/app-spec 0.5.0 → 0.7.1

package/dist/src/blueprint.d.ts

@@ -1,16 +1,25 @@
 import type { Spec } from "./schema.js";
+import { type KeptType } from "./memory.js";
 export type BlueprintV1 = {
     v: 1;
     purpose: string;
     screens: {
         id: string;
         says: string;
+        states?: {
+            empty?: string;
+            loading?: string;
+            offline?: string;
+            error?: string;
+        };
     }[];
     data: {
         version: number;
         keeps: {
             key: string;
             what: string;
+            shape?: Record<string, KeptType>;
+            personal?: boolean;
         }[];
     };
     journeys: Spec["journeys"];
@@ -20,9 +29,14 @@ export type BlueprintV1 = {
     icon?: string;
     category?: string;
     tags?: string[];
+    screen?: {
+        orientation?: "portrait" | "landscape" | "any";
+        fullscreen?: boolean;
+    };
     design: {
         palette: string[];
         notes: string;
+        tokens?: Record<string, string>;
     };
 };
 export declare function deriveBlueprint(spec: Spec): BlueprintV1;

package/dist/src/blueprint.js

@@ -1,3 +1,41 @@
+import { keptShape } from "./memory.js";
+import { rgbOf } from "./design.js";
+/** A blueprint's tokens are at most this many, by role (CloudCrane's blueprint takes 40). */
+const MAX_TOKENS = 40;
+/**
+ * The design tokens by role, as CloudCrane's blueprint holds them: colours as #hex (light as color.<role>, dark as
+ * color.dark.<role>), the corner radius and the font. Names as the spec has them, lower-case.
+ */
+function rolesOf(tokens) {
+    const out = {};
+    const hex = (v) => {
+        const rgb = rgbOf(v);
+        return rgb ? `#${rgb.map((c) => c.toString(16).padStart(2, "0")).join("")}` : null;
+    };
+    const tree = (tokens ?? {});
+    const colours = (group, prefix) => {
+        if (!group || typeof group !== "object")
+            return;
+        for (const [role, node] of Object.entries(group)) {
+            if (role.startsWith("$") || !node || typeof node !== "object" || !("$value" in node))
+                continue;
+            const h = hex(node.$value);
+            if (h && /^[a-z][a-z0-9-]*$/.test(role))
+                out[`${prefix}.${role}`] = h;
+        }
+    };
+    colours(tree["color"], "color");
+    colours(tree["dark"]?.["color"], "color.dark");
+    const radius = tree["border-radius"]?.["$value"];
+    if (radius && typeof radius.value === "number" && typeof radius.unit === "string")
+        out["border-radius"] = `${radius.value}${radius.unit}`;
+    const font = tree["font-family"]?.["$value"];
+    if (typeof font === "string")
+        out["font-family"] = font.slice(0, 100);
+    else if (Array.isArray(font))
+        out["font-family"] = font.map(String).join(", ").slice(0, 100);
+    return Object.fromEntries(Object.entries(out).slice(0, MAX_TOKENS));
+}
 const literal = (v) => (typeof v === "string" ? v.replace(/\$\{[^}]*\}/g, "…").trim() : null);
 const list = (xs, max = 6) => {
     const u = [...new Set(xs.filter(Boolean))];
@@ -43,13 +81,23 @@ function palette(tokens) {
 }
 export function deriveBlueprint(spec) {
     const saved = spec.data.initial && typeof spec.data.initial === "object" ? Object.keys(spec.data.initial) : [];
+    const shape = keptShape(spec.data.schema);
+    const tokens = rolesOf(spec.tokens);
     return {
         v: 1,
         purpose: spec.module.purpose,
-        screens: [{ id: spec.module.id, says: screenWords(spec) }],
+        // The screens as the spec describes them, with their states; else one, in the surface's own words.
+        screens: spec.screens ?? [{ id: spec.module.id, says: screenWords(spec) }],
         data: {
             version: spec.data.version,
-            keeps: [{ key: spec.data.key, what: saved.length ? `On this phone: ${list(saved)}` : "What you enter, on this phone" }],
+            keeps: [
+                {
+                    key: spec.data.key,
+                    what: saved.length ? `On this phone: ${list(saved)}` : "What you enter, on this phone",
+                    ...(Object.keys(shape).length ? { shape } : {}),
+                    ...(spec.data.personal?.length ? { personal: true } : {}),
+                },
+            ],
         },
         journeys: spec.journeys,
         promises: spec.promises,
@@ -58,6 +106,11 @@ export function deriveBlueprint(spec) {
         ...(spec.module.icon ? { icon: spec.module.icon } : {}),
         ...(spec.module.category ? { category: spec.module.category } : {}),
         ...(spec.module.tags?.length ? { tags: spec.module.tags } : {}),
-        design: { palette: palette(spec.tokens), notes: `Built from a CloudCrane spec, runtime ${spec.manifest.runtime}.` },
+        ...(spec.screen ? { screen: spec.screen } : {}),
+        design: {
+            palette: palette(spec.tokens),
+            notes: `Built from a CloudCrane spec, runtime ${spec.manifest.runtime}.`,
+            ...(Object.keys(tokens).length ? { tokens } : {}),
+        },
     };
 }

package/dist/src/design.d.ts

@@ -0,0 +1,16 @@
+import type { Problem } from "./a2ui.js";
+import type { Spec } from "./schema.js";
+/** The colour roles every screen uses: the page, and its main action. */
+export declare const CORE_ROLES: readonly ["background", "on-background", "primary", "on-primary"];
+/** Each "on" colour and what it sits on, read as text. */
+export declare const TEXT_PAIRS: [string, string][];
+/** WCAG 2.2 minimum contrast for normal-size text. */
+export declare const TEXT_CONTRAST = 4.5;
+/** A colour token's value as [r, g, b] 0-255, from #rgb, #rrggbb (or #rrggbbaa) or DTCG srgb components; null otherwise. */
+export declare function rgbOf(value: unknown): [number, number, number] | null;
+/** WCAG contrast ratio between two colours, 1 to 21. */
+export declare function contrast(a: [number, number, number], b: [number, number, number]): number;
+/** What could look better: the colour roles, their contrast in light and dark, and token types the runtime can't draw. */
+export declare function designWarnings(spec: Spec): Problem[];
+/** What could work better: each screen's empty, offline and error states, said. */
+export declare function statesWarnings(spec: Spec): Problem[];

package/dist/src/design.js

@@ -0,0 +1,137 @@
+// Warnings, not refusals: what makes an app look good and work well, measured from the spec alone.
+//
+// How it looks: the colour roles a screen needs are there, and each text colour reads on what it sits on (WCAG 2.2
+// contrast, 4.5:1 for text), in light and, when the spec has them, dark colours (tokens.dark). Token types the
+// runtime can't draw are said rather than silently dropped.
+// What it does: a screen that lists saved things says what it shows when there are none, and an app that talks to a
+// site says what it shows offline and when the site fails.
+/** The colour roles every screen uses: the page, and its main action. */
+export const CORE_ROLES = ["background", "on-background", "primary", "on-primary"];
+/** Each "on" colour and what it sits on, read as text. */
+export const TEXT_PAIRS = [
+    ["on-background", "background"],
+    ["on-surface", "surface"],
+    ["on-primary", "primary"],
+    ["on-input", "input"],
+    ["error", "background"],
+];
+/** WCAG 2.2 minimum contrast for normal-size text. */
+export const TEXT_CONTRAST = 4.5;
+/** DTCG types the runtime has no CSS for. */
+const UNDRAWN = new Set(["shadow", "typography", "gradient", "border", "transition", "strokeStyle", "cubicBezier"]);
+/** A colour token's value as [r, g, b] 0-255, from #rgb, #rrggbb (or #rrggbbaa) or DTCG srgb components; null otherwise. */
+export function rgbOf(value) {
+    if (typeof value === "string") {
+        const hex = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(value.trim());
+        if (!hex)
+            return null;
+        const h = hex[1].length === 3 ? [...hex[1]].map((c) => c + c).join("") : hex[1].slice(0, 6);
+        return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+    }
+    if (value && typeof value === "object") {
+        const o = value;
+        if (typeof o["hex"] === "string")
+            return rgbOf(o["hex"]);
+        if (o["colorSpace"] === "srgb" && Array.isArray(o["components"]) && o["components"].length >= 3)
+            return o["components"].slice(0, 3).map((c) => Math.round(Math.max(0, Math.min(1, Number(c))) * 255));
+    }
+    return null;
+}
+/** WCAG relative luminance. */
+const luminance = ([r, g, b]) => {
+    const [lr, lg, lb] = [r, g, b].map((c) => {
+        const x = c / 255;
+        return x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+};
+/** WCAG contrast ratio between two colours, 1 to 21. */
+export function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
+/** The color.* tokens of a tree, by role, as written. */
+function colours(tree) {
+    const out = new Map();
+    const color = tree && typeof tree === "object" ? tree["color"] : undefined;
+    if (!color || typeof color !== "object")
+        return out;
+    for (const [k, v] of Object.entries(color))
+        if (!k.startsWith("$") && v && typeof v === "object" && "$value" in v)
+            out.set(k, v["$value"]);
+    return out;
+}
+/** Every token's $type that the runtime can't draw, with where it is. */
+function undrawn(tree, path = [], type) {
+    if (!tree || typeof tree !== "object")
+        return [];
+    const node = tree;
+    const t = typeof node["$type"] === "string" ? node["$type"] : type;
+    if ("$value" in node)
+        return t && UNDRAWN.has(t) ? [`${path.join(".")} (${t})`] : [];
+    return Object.entries(node).flatMap(([k, v]) => (k.startsWith("$") ? [] : undrawn(v, [...path, k], t)));
+}
+function themeWarnings(scheme, roles) {
+    const at = scheme === "light" ? "tokens.color" : "tokens.dark.color";
+    const out = [];
+    for (const [text, under] of TEXT_PAIRS) {
+        const a = roles.get(text);
+        const b = roles.get(under);
+        if (a === undefined || b === undefined)
+            continue;
+        const fg = rgbOf(a);
+        const bg = rgbOf(b);
+        if (!fg || !bg)
+            continue;
+        const ratio = contrast(fg, bg);
+        if (ratio < TEXT_CONTRAST)
+            out.push({ at: `${at}.${text}`, problem: `${text} on ${under} is ${ratio.toFixed(1)}:1; text needs at least ${TEXT_CONTRAST}:1 to read (WCAG)` });
+    }
+    return out;
+}
+/** What could look better: the colour roles, their contrast in light and dark, and token types the runtime can't draw. */
+export function designWarnings(spec) {
+    const out = [];
+    const light = colours(spec.tokens);
+    for (const role of CORE_ROLES)
+        if (!light.has(role))
+            out.push({ at: "tokens.color", problem: `no color.${role}: every screen uses it` });
+    out.push(...themeWarnings("light", light));
+    const darkTree = spec.tokens["dark"];
+    if (darkTree) {
+        // Dark colours replace the light ones they name; the rest stay as they are.
+        const dark = new Map([...light, ...colours(darkTree)]);
+        out.push(...themeWarnings("dark", dark));
+    }
+    else {
+        out.push({ at: "tokens", problem: "no dark colours (tokens.dark): the app stays light when the phone is set to dark" });
+    }
+    for (const where of undrawn(spec.tokens))
+        out.push({ at: `tokens.${where.split(" ")[0]}`, problem: `the runtime can't draw ${where} yet; it's left out of the page` });
+    return out;
+}
+/** Whether a surface shows a list of things (an A2UI List, or a view of saved data). */
+function listsThings(spec) {
+    if (spec.data.views.length)
+        return true;
+    return spec.surface.messages.some((m) => (m.updateComponents?.components ?? []).some((c) => c.component === "List"));
+}
+/** What could work better: each screen's empty, offline and error states, said. */
+export function statesWarnings(spec) {
+    const out = [];
+    const online = spec.network.length > 0;
+    if (!spec.screens) {
+        if (listsThings(spec) || online)
+            out.push({ at: "screens", problem: "no screens described: say what each shows when it's empty, offline or something fails" });
+        return out;
+    }
+    // Said once for the app, not per screen: not every screen lists things or goes online.
+    const has = (state) => spec.screens.some((s) => s.states?.[state]);
+    if (listsThings(spec) && !has("empty"))
+        out.push({ at: "screens", problem: "no empty state: say what a screen shows before anything is saved" });
+    if (online && !has("offline"))
+        out.push({ at: "screens", problem: "no offline state: say what it shows without a connection" });
+    if (online && !has("error"))
+        out.push({ at: "screens", problem: `no error state: say what it shows when ${spec.network[0].site} fails` });
+    return out;
+}

package/dist/src/fidelity.d.ts

@@ -0,0 +1,17 @@
+import type { Problem } from "./a2ui.js";
+import type { Spec } from "./schema.js";
+/** The functions with no example to reproduce, in one warning that names them. */
+export declare function rulesWarnings(spec: Pick<Spec, "logic">): Problem[];
+export type CatalogUse = {
+    /** Each catalog component the screens place, and how many times. */
+    catalog: Record<string, number>;
+    /** Each coded component the screens place, its kit, and the native widget it replaces when the spec says. */
+    coded: {
+        name: string;
+        kit: "game" | "page";
+        replaces: string | null;
+        placed: number;
+    }[];
+};
+/** What a spec's screens are drawn with. A page spec (the whole app as one page) counts as its one coded component. */
+export declare function catalogUse(spec: Pick<Spec, "surface" | "components">): CatalogUse;

package/dist/src/fidelity.js

@@ -0,0 +1,36 @@
+// How closely a spec can be shown to copy the app it came from.
+// - Rules with no examples: nothing checks they do what the original does (a warning; the compiler checks every example
+//   a rule has, so one recorded from the original app is proof).
+// - What the screens are drawn with: the catalog's components, and the coded components standing in for what the
+//   catalog can't draw, with the native widget each replaces. `blackbox coverage` adds these up across specs, so the
+//   catalog grows where ports need it most.
+/** The functions with no example to reproduce, in one warning that names them. */
+export function rulesWarnings(spec) {
+    const shown = new Set(spec.logic.vectors.map((v) => v.fn));
+    const bare = Object.keys(spec.logic.functions).filter((fn) => !shown.has(fn));
+    if (!bare.length)
+        return [];
+    const [one] = bare;
+    return [
+        {
+            at: bare.length === 1 ? `/logic/functions/${one}` : "/logic/functions",
+            problem: `${bare.length === 1 ? `${one} has` : `${bare.join(", ")} have`} no examples: nothing checks ${bare.length === 1 ? "it does" : "they do"} what the original does. Record some from the app (from: app) or its tests`,
+        },
+    ];
+}
+/** What a spec's screens are drawn with. A page spec (the whole app as one page) counts as its one coded component. */
+export function catalogUse(spec) {
+    const catalog = {};
+    const placed = {};
+    for (const m of spec.surface.messages)
+        for (const c of m.updateComponents?.components ?? []) {
+            if (typeof c.component !== "string")
+                continue;
+            if (c.component === "Coded" && typeof c.use === "string")
+                placed[c.use] = (placed[c.use] ?? 0) + 1;
+            else
+                catalog[c.component] = (catalog[c.component] ?? 0) + 1;
+        }
+    const coded = Object.entries(spec.components).map(([name, c]) => ({ name, kit: c.kit, replaces: c.replaces ?? null, placed: placed[name] ?? 0 }));
+    return { catalog, coded };
+}

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 export { A2UI_VERSION, BASIC_CATALOG, surfaceProblems, type Catalog, type Problem } from "./a2ui.js";
-export { Id, Pointer, PointerPattern, SpecSchema, Tokens, type Spec, type TokenNode } from "./schema.js";
+export { GAP_KINDS, Id, Pointer, PointerPattern, SpecSchema, Tokens, type Spec, type TokenNode } from "./schema.js";
 export { validateSpec } from "./validate.js";
 export { canonical } from "./canonical.js";
 export { specJsonSchema } from "./jsonschema.js";
@@ -9,3 +9,7 @@ export { CLOUDCRANE_CATALOG, CLOUDCRANE_CATALOG_ID, catalogFor, cloudcraneCatalo
 export { deriveBlueprint, type BlueprintV1 } from "./blueprint.js";
 export { USES, USE_NAMES, NEEDS_ORIGIN, featuresOf, type Use } from "./uses.js";
 export { pageOf, pageProblems, wrapPage, type PageApp } from "./page.js";
+export { designWarnings, statesWarnings, contrast, rgbOf, CORE_ROLES, TEXT_PAIRS, TEXT_CONTRAST } from "./design.js";
+export { memoryProblems, keptShape, type KeptType } from "./memory.js";
+export { reachProblems, hostsNamedIn, buildsAddressAtRuntime } from "./reach.js";
+export { rulesWarnings, catalogUse, type CatalogUse } from "./fidelity.js";

package/dist/src/index.js

@@ -1,7 +1,7 @@
 // The CloudCrane app spec: its schema, the A2UI surface check, canonical JSON
 // and the JSON Schema export. See the repo README.
 export { A2UI_VERSION, BASIC_CATALOG, surfaceProblems } from "./a2ui.js";
-export { Id, Pointer, PointerPattern, SpecSchema, Tokens } from "./schema.js";
+export { GAP_KINDS, Id, Pointer, PointerPattern, SpecSchema, Tokens } from "./schema.js";
 export { validateSpec } from "./validate.js";
 export { canonical } from "./canonical.js";
 export { specJsonSchema } from "./jsonschema.js";
@@ -11,3 +11,7 @@ export { CLOUDCRANE_CATALOG, CLOUDCRANE_CATALOG_ID, catalogFor, cloudcraneCatalo
 export { deriveBlueprint } from "./blueprint.js";
 export { USES, USE_NAMES, NEEDS_ORIGIN, featuresOf } from "./uses.js";
 export { pageOf, pageProblems, wrapPage } from "./page.js";
+export { designWarnings, statesWarnings, contrast, rgbOf, CORE_ROLES, TEXT_PAIRS, TEXT_CONTRAST } from "./design.js";
+export { memoryProblems, keptShape } from "./memory.js";
+export { reachProblems, hostsNamedIn, buildsAddressAtRuntime } from "./reach.js";
+export { rulesWarnings, catalogUse } from "./fidelity.js";

package/dist/src/leak.js

@@ -44,6 +44,15 @@ const RULES = [
         test: re(/\b(sk|pk|rk)[-_](live|test|proj)?[-_]?[A-Za-z0-9]{20,}\b|\bAIza[0-9A-Za-z_-]{35}\b|\bgh[pousr]_[A-Za-z0-9]{36}\b|\bxox[abpr]-[A-Za-z0-9-]{10,}/),
     },
     { kind: "secret", why: "a JSON Web Token", test: re(/\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\./) },
+    // After secretlint's recommended preset: the formats it knows, beyond the ones above.
+    { kind: "secret", why: "an AWS secret access key", test: re(/aws_?secret_?access_?key["'\s:=]+[A-Za-z0-9/+=]{40}\b/i) },
+    { kind: "secret", why: "an npm token", test: re(/\bnpm_[A-Za-z0-9]{36}\b/) },
+    { kind: "secret", why: "a GitHub token", test: re(/\bgithub_pat_[A-Za-z0-9_]{60,}\b/) },
+    { kind: "secret", why: "an Anthropic or OpenAI key", test: re(/\bsk-(ant-(api|admin)\d{2}-|proj-)[A-Za-z0-9_-]{20,}/) },
+    { kind: "secret", why: "a Slack webhook", test: re(/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/) },
+    { kind: "secret", why: "a SendGrid key", test: re(/\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/) },
+    { kind: "secret", why: "a Shopify token", test: re(/\bshp(at|ss|ca|pa)_[a-fA-F0-9]{32}\b/) },
+    { kind: "secret", why: "a password in an address", test: re(/\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]{3,}@[^\s/]+/i) },
     { kind: "secret", why: "a private key", test: re(/-----BEGIN [A-Z ]*PRIVATE KEY-----/) },
     { kind: "secret", why: "a long random-looking string", test: highEntropy },
     { kind: "personal", why: "an email address", test: re(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/) },

package/dist/src/logic.js

@@ -172,7 +172,20 @@ export function logicProblems(spec) {
     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);
+    let rules;
+    try {
+        rules = new Rules(spec.logic);
+    }
+    catch (e) {
+        // A function named like one CEL already has (double, int, size...) can't be registered: say which, don't crash.
+        const taken = Object.keys(spec.logic.functions).find((n) => e.message.includes(`'${n}(`) || e.message.includes(` ${n}(`));
+        return [
+            {
+                at: taken ? `/logic/functions/${token(taken)}` : "/logic/functions",
+                problem: `${taken ? `"${taken}" is` : "a function name is"} already a CEL function: name it something else`,
+            },
+        ];
+    }
     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]),

package/dist/src/memory.d.ts

@@ -0,0 +1,7 @@
+import type { Problem } from "./a2ui.js";
+import type { Spec } from "./schema.js";
+/** CloudCrane's kept-field types (its blueprint's keeps[].shape). */
+export type KeptType = "text" | "number" | "yes/no" | "date" | "list" | "object";
+export declare function memoryProblems(spec: Spec): Problem[];
+/** Each top-level saved field and its type, in CloudCrane's words. */
+export declare function keptShape(schema: Record<string, unknown>): Record<string, KeptType>;

package/dist/src/memory.js

@@ -0,0 +1,81 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+const ajv = () => new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
+/** The schema as Ajv takes it: any $schema line names a draft this one reads the same for what specs use. */
+const plain = (schema) => {
+    const { $schema: _s, ...rest } = schema;
+    return rest;
+};
+export function memoryProblems(spec) {
+    const problems = [];
+    let validate;
+    try {
+        validate = ajv().compile(plain(spec.data.schema));
+    }
+    catch (err) {
+        return [{ at: "data.schema", problem: `isn't a JSON Schema: ${err instanceof Error ? err.message : String(err)}` }];
+    }
+    if (spec.data.initial !== undefined && !validate(spec.data.initial))
+        for (const e of validate.errors ?? [])
+            problems.push({ at: `data.initial${e.instancePath.replace(/\//g, ".")}`, problem: `doesn't fit data.schema: ${e.message ?? "invalid"}` });
+    // Every step from 1 to the current version, once each, so any older phone can come up to date. A page spec (an HTML
+    // app as a spec) moves its own data in its own code, as the page it is, so it has no migrations to check.
+    if (spec.page)
+        return [...problems, ...personalProblems(spec)];
+    const steps = new Map();
+    for (const m of spec.data.migrations)
+        steps.set(m.from, (steps.get(m.from) ?? 0) + 1);
+    for (let from = 1; from < spec.data.version; from++) {
+        const n = steps.get(from) ?? 0;
+        if (n === 0)
+            problems.push({ at: "data.migrations", problem: `no step from version ${from} to ${from + 1}: a phone still on ${from} would lose its data` });
+        if (n > 1)
+            problems.push({ at: "data.migrations", problem: `${n} steps from version ${from}; there must be one` });
+    }
+    return [...problems, ...personalProblems(spec)];
+}
+/** Personal fields name something the saved data has. */
+function personalProblems(spec) {
+    return (spec.data.personal ?? []).flatMap((pointer) => pointsInto(spec.data.schema, pointer) ? [] : [{ at: `data.personal ${pointer}`, problem: "the saved data has no such field (data.schema)" }]);
+}
+/** Whether a JSON Pointer names a field the schema describes (properties all the way down; arrays and maps by their items). */
+function pointsInto(schema, pointer) {
+    if (pointer === "")
+        return true;
+    let node = schema;
+    for (const raw of pointer.split("/").slice(1)) {
+        const part = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (!node || typeof node !== "object")
+            return false;
+        const props = node["properties"];
+        if (props && part in props)
+            node = props[part];
+        else if (node["items"] && /^\d+$|^\*$/.test(part))
+            node = node["items"];
+        else if (node["additionalProperties"] && typeof node["additionalProperties"] === "object")
+            node = node["additionalProperties"];
+        else
+            return false;
+    }
+    return true;
+}
+/** Each top-level saved field and its type, in CloudCrane's words. */
+export function keptShape(schema) {
+    const props = (schema["properties"] ?? {});
+    const out = {};
+    for (const [name, p] of Object.entries(props).slice(0, 40)) {
+        const type = Array.isArray(p["type"]) ? p["type"].find((t) => t !== "null") : p["type"];
+        out[name.slice(0, 40)] =
+            type === "string"
+                ? p["format"] === "date" || p["format"] === "date-time"
+                    ? "date"
+                    : "text"
+                : type === "number" || type === "integer"
+                    ? "number"
+                    : type === "boolean"
+                        ? "yes/no"
+                        : type === "array"
+                            ? "list"
+                            : "object";
+    }
+    return out;
+}

package/dist/src/reach.d.ts

@@ -0,0 +1,7 @@
+import type { Problem } from "./a2ui.js";
+import type { Spec } from "./schema.js";
+/** Every host an https:// or wss:// address in the code names, lower-case, once each. */
+export declare function hostsNamedIn(code: string): string[];
+/** Whether a request's address is put together while the app runs, so no one can read which site it reaches. */
+export declare function buildsAddressAtRuntime(code: string): boolean;
+export declare function reachProblems(spec: Spec): Problem[];

package/dist/src/reach.js

@@ -0,0 +1,102 @@
+import { USE_NAMES } from "./uses.js";
+// What it can reach, checked against the code: a coded or page component's code may name only the sites in `network`
+// and use only the device features in `uses`, so what the person is shown before the app opens is everything it does.
+// Refusals, not warnings. The same reading CloudCrane's checks give an app's code (its apps.rules.ts and
+// blueprints/capabilities.ts), so a spec that passes here passes there.
+/** Example domains and schema.org name no site an app talks to. */
+const EXAMPLE_DOMAIN = /^(?:[a-z0-9-]+\.)*example\.(?:com|org|net)$|^(?:[a-z0-9-]+\.)+(?:example|test|invalid|localhost)$/i;
+const notASite = (host) => EXAMPLE_DOMAIN.test(host.replace(/:\d+$/, "")) || /^(?:[a-z0-9-]+\.)*schema\.org(?::\d+)?$/.test(host);
+/** Links and the page's own tags carry nothing with them: their addresses aren't sites the code talks to. */
+const OWN_TAG = /<(a|script|link|iframe|embed|object|form)\b[^>]*>/gi;
+const ADDRESS_ATTR = /(?<=\s)(href|src|data|action)\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi;
+/** Every host an https:// or wss:// address in the code names, lower-case, once each. */
+export function hostsNamedIn(code) {
+    const text = code.replace(OWN_TAG, (tag) => tag.replace(ADDRESS_ATTR, '$1=""'));
+    const hosts = new Set();
+    for (const m of text.matchAll(/\b(?:https|wss):\/\/([^\s/?#"'`<>\\()[\]{},;$]+)/gi)) {
+        const authority = m[1];
+        const host = authority
+            .slice(authority.lastIndexOf("@") + 1)
+            .toLowerCase()
+            .replace(/\.$/, "")
+            .replace(/:443$/, "");
+        if (host && !notASite(host))
+            hosts.add(host);
+    }
+    return [...hosts];
+}
+/** Calls that reach the network, and where their address starts. */
+const REQUESTS = [
+    /(?<![\w$])fetch\s*\(\s*/g,
+    /\bnew\s+(?:WebSocket|EventSource)\s*\(\s*/g,
+    /\.sendBeacon\s*\(\s*/g,
+    /\.open\s*\(\s*(["'`])[A-Za-z]+\1\s*,\s*/g,
+];
+/** Whether a request's address is put together while the app runs, so no one can read which site it reaches. */
+export function buildsAddressAtRuntime(code) {
+    for (const pattern of REQUESTS) {
+        if (pattern.source.startsWith("\\.open") && !/XMLHttpRequest/.test(code))
+            continue;
+        for (const m of code.matchAll(pattern)) {
+            const rest = code.slice(m.index + m[0].length, m.index + m[0].length + 300);
+            const quote = rest[0];
+            if (quote !== '"' && quote !== "'" && quote !== "`")
+                return true;
+            const end = rest.indexOf(quote, 1);
+            let start = rest.slice(1, end === -1 ? undefined : end);
+            if (quote === "`" && start.includes("${"))
+                start = start.slice(0, start.indexOf("${"));
+            if (!start)
+                return true;
+            const absolute = /^([a-z][a-z0-9+.-]*:|\/\/)/i.test(start);
+            if (absolute && !/^(?:[a-z][a-z0-9+.-]*:)?\/\/[a-z0-9-]+(\.[a-z0-9-]+)*/i.test(start))
+                return true;
+        }
+    }
+    return false;
+}
+/** How code uses each device feature a spec can declare. */
+const USED_BY = {
+    camera: [/\bgetUserMedia\b/],
+    microphone: [/\bgetUserMedia\b/],
+    location: [/\bgeolocation\b/],
+    motion: [/\bDevice(Motion|Orientation)Event\b/, /\bdevice(motion|orientation)\b/],
+    "screen-awake": [/\bwakeLock\b/],
+    gamepad: [/\bgetGamepads\b/, /\bgamepad(dis)?connected\b/],
+    voice: [/\b(webkit)?SpeechRecognition\b/],
+    contacts: [/\bnavigator\.contacts\b/, /\bContactsManager\b/],
+    nfc: [/\bNDEF(Reader|Message|Record)\b/],
+};
+/** Features a spec can't declare, so code that uses them is refused. */
+const NOT_FOR_SPECS = [
+    ["Bluetooth", /\bnavigator\.bluetooth\b/],
+    ["direct connections to other phones (RTCPeerConnection)", /\b(webkit)?RTCPeerConnection\b/],
+    ["USB, serial or HID devices", /\bnavigator\.(usb|serial|hid)\b/],
+    ["payments", /\bPaymentRequest\b/],
+];
+export function reachProblems(spec) {
+    const problems = [];
+    const sites = new Set(spec.network.map((n) => n.site));
+    const declared = new Set(spec.uses.map((u) => u.what));
+    for (const [name, component] of Object.entries(spec.components)) {
+        const at = `components.${name}.code`;
+        const code = component.code;
+        for (const host of hostsNamedIn(code))
+            if (!sites.has(host))
+                problems.push({ at, problem: `talks to ${host}, which network doesn't list: add it with why and what it's sent, or take it out` });
+        if (buildsAddressAtRuntime(code))
+            problems.push({ at, problem: "builds a request's address while it runs, so no one can tell which site it reaches: write each address out in full" });
+        // camera and microphone share getUserMedia: either one declared covers it.
+        for (const what of USE_NAMES) {
+            if (declared.has(what) || !USED_BY[what].some((p) => p.test(code)))
+                continue;
+            if ((what === "camera" || what === "microphone") && (declared.has("camera") || declared.has("microphone")))
+                continue;
+            problems.push({ at, problem: `uses ${what} but uses doesn't declare it: add it with why, or take it out` });
+        }
+        for (const [what, pattern] of NOT_FOR_SPECS)
+            if (pattern.test(code))
+                problems.push({ at, problem: `uses ${what}, which a spec can't declare` });
+    }
+    return problems;
+}