@cloudcrane/blackbox 0.4.0 → 0.7.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
-import { build, diff, extract, preview, validate } from "./commands.js";
+import { build, coverage, diff, extract, preview, validate } from "./commands.js";
 // blackbox: write a CloudCrane app spec from an app's code, see what a code
 // change touched, and validate, build and preview a spec.
 const USAGE = `blackbox <command> <path> [options]
@@ -8,6 +8,7 @@ const USAGE = `blackbox <command> <path> [options]
   extract  <repo> [--hints FILE] [--out DIR]   write a spec from an app's code and its blackbox.hints.json
   diff     <repo> [--module ID] [--range A..B] which parts of the spec a code change touched
   validate <spec.json>                 check a spec: schema, A2UI surface, rules, leaks
+  coverage <spec.json...>              what the specs are drawn with: catalog components, and the native widgets coded components replace
   build    <spec.json> [--out FILE]    build the app page (the same bytes every time)
   preview  <spec.json> [--port N]      serve the app here, under CloudCrane's security policy`;
 const print = (o) => {
@@ -43,6 +44,8 @@ async function main(argv) {
         return print(diff(file, values.module, values.range));
     if (command === "validate")
         return print(validate(file));
+    if (command === "coverage")
+        return print(coverage(positionals.slice(1)));
     if (command === "build")
         return print(build(file, values.out));
     if (command === "preview") {

package/dist/commands.d.ts

@@ -3,8 +3,14 @@ export type Outcome = {
     ok: boolean;
     lines: string[];
 };
-/** blackbox validate <spec.json>: every problem, or that it's ready. */
+/** blackbox validate <spec.json>: every problem, or that it's ready; and what would make it better, either way. */
 export declare function validate(file: string): Outcome;
+/**
+ * blackbox coverage <spec.json...>: what the specs' screens are drawn with, added up: each catalog component and how
+ * often it's placed, and each coded component by the native widget it replaces, most needed first, so the catalog
+ * grows where ports fall back to code. Specs that don't validate are counted as they're written, and named.
+ */
+export declare function coverage(files: string[]): Outcome;
 /** blackbox build <spec.json> [--out app.html]: the app page and its hash. */
 export declare function build(file: string, out?: string): Outcome;
 /** blackbox preview <spec.json> [--port 5420]: the app as a phone gets it, on this machine, under CloudCrane's policy. */

package/dist/commands.js

@@ -1,8 +1,8 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
-import { validateSpec } from "@cloudcrane/app-spec";
+import { catalogUse, featuresOf, validateSpec } from "@cloudcrane/app-spec";
 import { compile, CompileError } from "@cloudcrane/app-runtime";
-import { appCsp } from "./csp.js";
+import { appCsp, appPermissions } from "./csp.js";
 import { extract as extractSpec } from "./extract.js";
 import { touchedBy } from "./diff.js";
 import { mkdirSync } from "node:fs";
@@ -15,15 +15,75 @@ const readSpec = (file) => {
         throw new Error(`Couldn't read ${file} as JSON: ${e.message}`);
     }
 };
-/** blackbox validate <spec.json>: every problem, or that it's ready. */
+/** blackbox validate <spec.json>: every problem, or that it's ready; and what would make it better, either way. */
 export function validate(file) {
-    const { spec, problems } = validateSpec(readSpec(file));
+    const { spec, problems, warnings } = validateSpec(readSpec(file));
+    const better = warnings.length
+        ? [`  ${warnings.length} thing${warnings.length === 1 ? "" : "s"} to make it better:`, ...warnings.map((w) => `    ${w.at}: ${w.problem}`)]
+        : [];
     if (spec)
         return {
             ok: true,
-            lines: [`${file}: ready. ${spec.journeys.length} journeys, ${spec.promises.length} promises, ${Object.keys(spec.logic.functions).length} rules.`],
+            lines: [
+                `${file}: ready. ${spec.journeys.length} journeys, ${spec.promises.length} promises, ${Object.keys(spec.logic.functions).length} rules.`,
+                ...gapLines(spec),
+                ...better,
+            ],
         };
-    return { ok: false, lines: [`${file}: ${problems.length} problem${problems.length === 1 ? "" : "s"}`, ...problems.map((p) => `  ${p.at}: ${p.problem}`)] };
+    return {
+        ok: false,
+        lines: [`${file}: ${problems.length} problem${problems.length === 1 ? "" : "s"}`, ...problems.map((p) => `  ${p.at}: ${p.problem}`), ...better],
+    };
+}
+const gapLines = (spec) => (spec.gaps?.length ? [`  Doesn't do what the original does: ${spec.gaps.map((g) => g.what.toLowerCase()).join("; ")}.`] : []);
+/**
+ * blackbox coverage <spec.json...>: what the specs' screens are drawn with, added up: each catalog component and how
+ * often it's placed, and each coded component by the native widget it replaces, most needed first, so the catalog
+ * grows where ports fall back to code. Specs that don't validate are counted as they're written, and named.
+ */
+export function coverage(files) {
+    const catalog = {};
+    const fallbacks = {};
+    const unreadable = [];
+    let coded = 0;
+    for (const file of files) {
+        const raw = readSpec(file);
+        let use;
+        try {
+            use = catalogUse({ surface: raw.surface, components: raw.components ?? {} });
+        }
+        catch {
+            unreadable.push(file);
+            continue;
+        }
+        for (const [c, n] of Object.entries(use.catalog))
+            catalog[c] = (catalog[c] ?? 0) + n;
+        for (const c of use.coded) {
+            coded++;
+            const key = c.replaces ?? (c.kit === "page" ? "(a whole page)" : "(a game, or replaces not said)");
+            const f = (fallbacks[key] ??= { specs: new Set(), placed: 0 });
+            f.specs.add(file);
+            f.placed += c.placed;
+        }
+    }
+    const byCount = (entries, n) => entries.sort(([a, x], [b, y]) => n(y) - n(x) || (a < b ? -1 : 1));
+    const placed = Object.values(catalog).reduce((a, b) => a + b, 0);
+    const share = placed + coded ? Math.round((placed / (placed + coded)) * 100) : 0;
+    return {
+        ok: !unreadable.length,
+        lines: [
+            `${files.length - unreadable.length} spec${files.length === 1 ? "" : "s"}: ${placed} catalog components placed, ${coded} coded component${coded === 1 ? "" : "s"} (${share}% drawn by the catalog).`,
+            "",
+            "Coded components, by what they replace (most needed in the catalog first):",
+            ...(coded
+                ? byCount(Object.entries(fallbacks), (f) => f.specs.size).map(([what, f]) => `  ${what}: ${f.specs.size} spec${f.specs.size === 1 ? "" : "s"}, placed ${f.placed} time${f.placed === 1 ? "" : "s"}`)
+                : ["  none"]),
+            "",
+            "Catalog components used:",
+            ...byCount(Object.entries(catalog), (n) => n).map(([c, n]) => `  ${c}: ${n}`),
+            ...unreadable.map((f) => `${f}: its surface couldn't be read`),
+        ],
+    };
 }
 /** blackbox build <spec.json> [--out app.html]: the app page and its hash. */
 export function build(file, out) {
@@ -44,6 +104,8 @@ export function preview(file, port = 5420) {
     const spec = readSpec(file);
     const { html } = compile(spec);
     const csp = appCsp((spec.network ?? []).map((n) => n.site));
+    // And the phone features it declares, nothing else, as CloudCrane serves it.
+    const permissions = appPermissions(featuresOf(spec.uses ?? []));
     const server = createServer((req, res) => {
         if (req.url !== "/" && req.url !== "/index.html") {
             res.writeHead(404).end();
@@ -52,6 +114,7 @@ export function preview(file, port = 5420) {
         res.writeHead(200, {
             "content-type": "text/html; charset=utf-8",
             "content-security-policy": csp,
+            "permissions-policy": permissions,
             "cache-control": "no-store",
             "x-content-type-options": "nosniff",
         });

package/dist/csp.d.ts

@@ -1 +1,3 @@
+/** The Permissions-Policy CloudCrane serves an app with: what its uses declare, and nothing else. */
+export declare function appPermissions(allowed: readonly string[]): string;
 export declare function appCsp(sites: readonly string[]): string;

package/dist/csp.js

@@ -3,6 +3,15 @@
 // the app will on a phone: no scripts, styles or fonts from other sites, no eval,
 // and only the sites the spec lists reachable.
 const SITE = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+/** Features no app may have, whatever it declares (CloudCrane's ALWAYS_OFF). */
+const ALWAYS_OFF = ["payment", "usb", "serial", "hid", "midi", "display-capture"];
+/** Every feature an app could ask for: each is allowed only when the spec's uses declare it (CloudCrane's permissionsPolicy). */
+const FEATURES = ["camera", "microphone", "geolocation", "accelerometer", "gyroscope", "magnetometer", "screen-wake-lock", "gamepad", "bluetooth"];
+/** The Permissions-Policy CloudCrane serves an app with: what its uses declare, and nothing else. */
+export function appPermissions(allowed) {
+    const on = new Set(allowed);
+    return [...FEATURES.map((f) => `${f}=${on.has(f) ? "*" : "()"}`), ...ALWAYS_OFF.map((f) => `${f}=()`)].join(", ");
+}
 export function appCsp(sites) {
     const listed = [...new Set(sites.map((s) => s.toLowerCase()))].filter((s) => SITE.test(s));
     const https = listed.map((s) => ` https://${s}`).join("");

package/dist/extract.d.ts

@@ -1,23 +1,42 @@
 import { type Problem, type Spec } from "@cloudcrane/app-spec";
-export declare const GENERATOR = "blackbox@0.4.0";
+export declare const GENERATOR = "blackbox@0.7.0";
 /** blackbox.hints.json: where things are, and what the readers can't find yet (as spec parts). */
 export type Hints = {
     module: Spec["module"];
-    /** roles: a theme colour's name → the token path(s) it sets, like ["color", "primary"] or [["color", "on-background"], ["color", "on-surface"]]. */
+    /**
+     * roles: a theme colour's name → the token path(s) it sets, like ["color", "primary"] or [["color", "on-background"], ["color", "on-surface"]].
+     * mode: one scheme only. Left out, a theme with both gives the light colours, and the dark ones as tokens.dark.
+     */
     theme?: {
         file: string;
         mode?: "dark" | "light";
         roles?: Record<string, string[] | string[][]>;
     };
+    /**
+     * files: modules of pure functions, translated to CEL; tests: their tests, read for examples; recorded: JSON Lines
+     * files of calls recorded while the original app ran ({"fn", "in", "out"} each), kept as examples `from: "app"`.
+     */
     rules?: {
         files: string[];
         tests?: string[];
+        recorded?: string[];
     };
+    /**
+     * What the original does that this one doesn't. Left out, it's suggested from the packages the app depends on
+     * (`manifests`, by default pubspec.yaml and package.json at the repo's root); given, it's the list as written.
+     */
+    gaps?: Spec["gaps"];
+    manifests?: string[];
     tokens?: Record<string, unknown>;
     surface: Spec["surface"];
     data: Spec["data"];
     logic?: Partial<Spec["logic"]>;
+    /** What it can reach: each site with why and what it's sent; the device features it uses. */
     network?: Spec["network"];
+    uses?: Spec["uses"];
+    /** What it does: each screen with its empty, loading, offline and error states; the orientation. */
+    screens?: Spec["screens"];
+    screen?: Spec["screen"];
     journeys: Spec["journeys"];
     promises?: Spec["promises"];
     tests?: Spec["tests"];
@@ -27,14 +46,45 @@ export type Citation = {
     file: string;
     lines: [number, number];
     hash: string;
-    how: "flutter-theme" | "ts-pure" | "ts-vectors" | "hint";
+    how: "flutter-theme" | "ts-pure" | "ts-vectors" | "app-recording" | "manifest" | "hint";
     symbol?: string;
 };
+/** How much of a spec was read from the app, rather than written in hints: the parts a reviewer checks by hand are the rest. */
+export type Coverage = {
+    /** Design tokens and rules read from the code, of all of them, as a whole percentage. */
+    fromCode: number;
+    tokens: {
+        code: number;
+        hints: number;
+    };
+    rules: {
+        code: number;
+        hints: number;
+    };
+    /** Rules with at least one example to reproduce, of all rules; and the examples by where they came from. */
+    checked: {
+        rules: number;
+        of: number;
+        examples: {
+            tests: number;
+            app: number;
+            hints: number;
+        };
+    };
+    /** What the screens are drawn with: catalog components placed, coded components defined, and what each replaces. */
+    screens: {
+        catalog: number;
+        coded: number;
+        replaces: string[];
+    };
+    gaps: number;
+};
 export type Provenance = {
     generator: string;
     spec: string;
     source: string;
     elements: Record<string, Citation[]>;
+    coverage?: Coverage;
 };
 export type Extracted = {
     spec: Spec | null;

package/dist/extract.js

@@ -1,10 +1,12 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { canonical, validateSpec } from "@cloudcrane/app-spec";
+import { canonical, catalogUse, validateSpec } from "@cloudcrane/app-spec";
 import { RUNTIME_VERSION } from "@cloudcrane/app-runtime";
 import { citeHash } from "veridic/citations";
+import { existsSync } from "node:fs";
 import { readFlutterTheme, ROLES } from "./readers/flutter-theme.js";
+import { gapsIn } from "./readers/gaps.js";
 import { translateModule } from "./readers/ts-pure.js";
 import { harvestVectors } from "./readers/ts-vectors.js";
 import { shingleLeaks } from "./shingles.js";
@@ -14,7 +16,7 @@ import { shingleLeaks } from "./shingles.js";
 // Pointer, with the file, lines and a hash of those lines (Veridic's citeHash),
 // and how it was found. The spec itself holds no code and no paths: the
 // validator and the leak gates refuse any.
-export const GENERATOR = "blackbox@0.4.0";
+export const GENERATOR = "blackbox@0.7.0";
 const escapePointer = (s) => s.replace(/~/g, "~0").replace(/\//g, "~1");
 const sha = (s) => createHash("sha256").update(s).digest("hex");
 export function extract(repo, hints) {
@@ -26,13 +28,16 @@ export function extract(repo, hints) {
         return { file, lines: [a, b], hash: citeHash(lines), how, ...(symbol ? { symbol } : {}) };
     };
     const elements = {};
+    // Files read as data (recorded calls, package manifests): part of the source's fingerprint, but not code, so not
+    // held to the copied-code check, which recorded examples would trip by design.
+    const data = new Set();
     const add = (pointer, c) => (elements[pointer] ??= []).push(c);
     const notes = [];
     const cited = new Set();
     // Tokens: the theme's colours by role, its font and radius; the hints may add or override.
     const tokens = {};
     if (hints.theme) {
-        const { file, mode = "dark", roles = {} } = hints.theme;
+        const { file, mode, roles = {} } = hints.theme;
         cited.add(file);
         const theme = readFlutterTheme(read(file));
         const map = { ...ROLES, ...roles };
@@ -44,6 +49,12 @@ export function extract(repo, hints) {
             for (const [group, name] of paths) {
                 (tokens[group] ??= { $type: "color" })[name] = { $value: mode === "dark" ? c.dark : c.light };
                 add(`/tokens/${escapePointer(group)}/${escapePointer(name)}`, cite(file, [c.line, c.line], "flutter-theme", c.name));
+                // Both schemes, unless one was asked for: the dark colour as tokens.dark, where it differs.
+                if (!mode && c.dark !== c.light) {
+                    const dark = (tokens["dark"] ??= {});
+                    (dark[group] ??= { $type: "color" })[name] = { $value: c.dark };
+                    add(`/tokens/dark/${escapePointer(group)}/${escapePointer(name)}`, cite(file, [c.line, c.line], "flutter-theme", c.name));
+                }
             }
         }
         if (theme.font) {
@@ -95,6 +106,46 @@ export function extract(repo, hints) {
         if (leftOut)
             notes.push(`- ${leftOut} test call${leftOut === 1 ? "" : "s"} in ${file.split("/").pop()} not read as vectors (in a loop, or not plain values)`);
     }
+    // Examples recorded from the original app as it ran: the strongest proof a rule does what the app did.
+    const MAX_APP_EXAMPLES = 20;
+    for (const file of hints.rules?.recorded ?? []) {
+        data.add(file);
+        const perFn = {};
+        const seen = new Set();
+        let unknown = 0;
+        let unread = 0;
+        read(file)
+            .split("\n")
+            .forEach((line, i) => {
+            if (!line.trim())
+                return;
+            let call;
+            try {
+                call = JSON.parse(line);
+            }
+            catch {
+                unread++;
+                return;
+            }
+            // At most 8 arguments, as a spec's examples allow.
+            if (typeof call.fn !== "string" || !Array.isArray(call.in) || call.in.length > 8 || !("out" in call))
+                return void unread++;
+            if (!(call.fn in functions) && !(call.fn in (hints.logic?.functions ?? {})))
+                return void unknown++;
+            const key = JSON.stringify([call.fn, call.in, call.out]);
+            if (seen.has(key) || (perFn[call.fn] ?? 0) >= MAX_APP_EXAMPLES)
+                return;
+            seen.add(key);
+            perFn[call.fn] = (perFn[call.fn] ?? 0) + 1;
+            add(`/logic/vectors/${vectors.length}`, cite(file, [i + 1, i + 1], "app-recording", call.fn));
+            vectors.push({ fn: call.fn, in: call.in, out: call.out, from: "app" });
+        });
+        const name = file.split("/").pop();
+        if (unknown)
+            notes.push(`- ${unknown} recorded call${unknown === 1 ? "" : "s"} in ${name} to functions the spec doesn't have`);
+        if (unread)
+            notes.push(`- ${unread} line${unread === 1 ? "" : "s"} in ${name} not read as a call ({"fn", "in", "out"})`);
+    }
     for (const [name, f] of Object.entries(hints.logic?.functions ?? {})) {
         if (name in functions)
             notes.push(`- ${name}: the hints' version replaces the translated one`);
@@ -107,9 +158,31 @@ export function extract(repo, hints) {
     }
     for (const pointer of Object.keys(hints.logic?.computed ?? {}))
         add(`/logic/computed/${escapePointer(pointer)}`, { file: "blackbox.hints.json", lines: [0, 0], hash: "", how: "hint" });
+    // Gaps: as the hints say, or suggested from the packages the app depends on.
+    let gaps = hints.gaps ?? [];
+    const manifests = hints.manifests ?? ["pubspec.yaml", "package.json"].filter((f) => existsSync(join(repo, f)));
+    const suggested = [];
+    for (const file of manifests) {
+        data.add(file);
+        for (const g of gapsIn(file, read(file))) {
+            if (hints.gaps) {
+                if (!hints.gaps.some((h) => h.kind === g.kind))
+                    suggested.push(`- ${g.what} (${g.package}, ${file})`);
+                continue;
+            }
+            if (gaps.length >= 20)
+                break;
+            add(`/gaps/${gaps.length}`, cite(file, [g.line, g.line], "manifest", g.package));
+            gaps.push({ kind: g.kind, what: g.what });
+        }
+    }
+    if (hints.gaps)
+        add("/gaps", { file: "blackbox.hints.json", lines: [0, 0], hash: "", how: "hint" });
+    gaps = gaps.slice(0, 20);
     // The source's fingerprint: every cited file's content, by name, hashed. A hash, never the code.
     const files = [...cited].sort();
-    const fingerprint = sha(files.map((f) => `${f}\0${sha(readFileSync(join(repo, f)))}`).join("\n"));
+    const all = [...new Set([...cited, ...data])].sort();
+    const fingerprint = sha(all.map((f) => `${f}\0${sha(readFileSync(join(repo, f)))}`).join("\n"));
     const draft = {
         v: 1,
         manifest: { runtime: RUNTIME_VERSION, generator: GENERATOR, source: { fingerprint: `sha256:${fingerprint}` } },
@@ -119,18 +192,23 @@ export function extract(repo, hints) {
         data: hints.data,
         logic: { consts: { ...consts, ...(hints.logic?.consts ?? {}) }, functions, computed: hints.logic?.computed ?? {}, vectors },
         network: hints.network ?? [],
+        ...(hints.uses ? { uses: hints.uses } : {}),
+        ...(hints.screens ? { screens: hints.screens } : {}),
+        ...(hints.screen ? { screen: hints.screen } : {}),
+        ...(gaps.length ? { gaps } : {}),
         journeys: hints.journeys,
         promises: hints.promises ?? [],
         tests: hints.tests ?? [],
         mods: hints.mods ?? { open: [], locked: [] },
     };
-    for (const part of ["surface", "data", "journeys", "promises", "tests", "mods", "network", "module"])
+    for (const part of ["surface", "data", "journeys", "promises", "tests", "mods", "network", "uses", "screens", "screen", "module"])
         if (part in hints)
             add(`/${part}`, { file: "blackbox.hints.json", lines: [0, 0], hash: "", how: "hint" });
-    const { spec, problems } = validateSpec(draft);
+    const { spec, problems, warnings } = validateSpec(draft);
     // The second gate: nothing in the spec (outside its CEL rules) repeats the source's own words.
     const shingles = shingleLeaks(draft, files.map(read));
-    const all = [...problems, ...shingles];
+    const refused = [...problems, ...shingles];
+    const coverage = coverageOf(draft, elements);
     const counts = {};
     for (const cs of Object.values(elements))
         for (const c of cs)
@@ -138,7 +216,7 @@ export function extract(repo, hints) {
     const report = [
         `# ${hints.module.name}: what Blackbox read`,
         "",
-        `Spec ${all.length ? `**not ready**: ${all.length} problem${all.length === 1 ? "" : "s"}` : "ready"}. Generated by ${GENERATOR} for runtime ${RUNTIME_VERSION}, from ${files.length} source files (fingerprint ${fingerprint.slice(0, 12)}).`,
+        `Spec ${refused.length ? `**not ready**: ${refused.length} problem${refused.length === 1 ? "" : "s"}` : "ready"}. Generated by ${GENERATOR} for runtime ${RUNTIME_VERSION}, from ${all.length} source files (fingerprint ${fingerprint.slice(0, 12)}).`,
         "",
         "## Where each part came from",
         "",
@@ -149,12 +227,72 @@ export function extract(repo, hints) {
         `Read from the code: ${Object.keys(tokens).length ? "design tokens, " : ""}${Object.keys(functions).length - Object.keys(hints.logic?.functions ?? {}).length} rules, ${vectors.filter((v) => v.from === "recorded").length} vectors from the module's own tests.`,
         "From hints: the screens, the saved-data shape, composed rules and computed values, journeys and promises.",
         "",
+        "## How much came from the code",
+        "",
+        ...coverageLines(coverage),
+        "",
+        "## What it doesn't do that the original does",
+        "",
+        ...(gaps.length ? gaps.map((g) => `- ${g.what} (${g.kind})`) : ["- nothing found; say so in the hints' gaps if the original does more"]),
+        ...(suggested.length ? ["", "Its packages suggest these too, which the hints' gaps don't list:", ...suggested] : []),
+        "",
         "## Left out",
         "",
         ...(notes.length ? notes : ["- nothing"]),
         "",
-        ...(all.length ? ["## Problems", "", ...all.map((p) => `- ${p.at}: ${p.problem}`), ""] : []),
+        ...(refused.length ? ["## Problems", "", ...refused.map((p) => `- ${p.at}: ${p.problem}`), ""] : []),
+        ...(warnings.length ? ["## To make it better", "", ...warnings.map((w) => `- ${w.at}: ${w.problem}`), ""] : []),
     ].join("\n");
-    const provenance = { generator: GENERATOR, spec: spec ? sha(canonical(spec)) : "", source: `sha256:${fingerprint}`, elements };
-    return { spec: all.length ? null : spec, draft, provenance, report, problems: all };
+    const provenance = { generator: GENERATOR, spec: spec ? sha(canonical(spec)) : "", source: `sha256:${fingerprint}`, elements, coverage };
+    return { spec: refused.length ? null : spec, draft, provenance, report, problems: refused };
+}
+/** Read from the code or written in hints, by element: an element read from the code has a citation that isn't a hint. */
+function coverageOf(spec, elements) {
+    const fromCode = (pointer) => (elements[pointer] ?? []).some((c) => c.how !== "hint");
+    const under = (prefix, depth) => Object.keys(elements).filter((p) => p.startsWith(prefix) && p.split("/").length === depth);
+    // Tokens: each colour /tokens/<group>/<name> (and dark ones, one deeper), or a whole token like /tokens/font-family.
+    const tokenPointers = Object.keys(elements).filter((p) => p.startsWith("/tokens/"));
+    const tokens = { code: tokenPointers.filter(fromCode).length, hints: tokenPointers.filter((p) => !fromCode(p)).length };
+    const fns = under("/logic/functions/", 4);
+    const rules = { code: fns.filter(fromCode).length, hints: fns.filter((p) => !fromCode(p)).length };
+    const vectors = spec.logic?.vectors ?? [];
+    const names = Object.keys(spec.logic?.functions ?? {});
+    const withExamples = names.filter((n) => vectors.some((v) => v.fn === n)).length;
+    const examples = {
+        tests: vectors.filter((v) => v.from === "recorded").length,
+        app: vectors.filter((v) => v.from === "app").length,
+        hints: vectors.filter((v) => v.from === "hint").length,
+    };
+    let screens = { catalog: 0, coded: 0, replaces: [] };
+    try {
+        const use = catalogUse({ surface: spec.surface, components: spec.components ?? {} });
+        screens = {
+            catalog: Object.values(use.catalog).reduce((a, b) => a + b, 0),
+            coded: use.coded.length,
+            replaces: use.coded.flatMap((c) => (c.replaces ? [c.replaces] : [])),
+        };
+    }
+    catch {
+        // A surface too malformed to read is reported as a problem; coverage just leaves it at nothing.
+    }
+    const read = tokens.code + rules.code;
+    const total = read + tokens.hints + rules.hints;
+    return {
+        fromCode: total ? Math.round((read / total) * 100) : 0,
+        tokens,
+        rules,
+        checked: { rules: withExamples, of: names.length, examples },
+        screens,
+        gaps: spec.gaps?.length ?? 0,
+    };
+}
+function coverageLines(c) {
+    const of = (part) => `${part.code} of ${part.code + part.hints}`;
+    return [
+        `**${c.fromCode}%** of the design tokens and rules were read from the code; the rest came from hints, to check by hand.`,
+        "",
+        `- Design tokens: ${of(c.tokens)} read from the code`,
+        `- Rules: ${of(c.rules)} read from the code; ${c.checked.rules} of ${c.checked.of} checked by examples (${c.checked.examples.app} recorded from the app, ${c.checked.examples.tests} from its tests, ${c.checked.examples.hints} from hints)`,
+        `- Screens: from hints, with ${c.screens.catalog} catalog components and ${c.screens.coded} coded component${c.screens.coded === 1 ? "" : "s"}${c.screens.replaces.length ? ` (standing in for ${c.screens.replaces.join(", ")})` : ""}`,
+    ];
 }

package/dist/readers/gaps.d.ts

@@ -0,0 +1,11 @@
+export type GapKind = "background" | "widget" | "notifications" | "purchases" | "accounts" | "sync" | "device" | "other";
+export type FoundGap = {
+    kind: GapKind;
+    what: string;
+    package: string;
+    line: number;
+};
+/** Package name (exact, or a prefix ending in "*") → what the app likely does with it that a web app can't yet. */
+export declare const KNOWN: [string, GapKind, string][];
+/** The gaps a manifest suggests, once each by what, in the order the packages are listed. */
+export declare function gapsIn(file: string, text: string): FoundGap[];

package/dist/readers/gaps.js

@@ -0,0 +1,89 @@
+// What an app does that a phone web app can't yet, read from the packages it depends on: Flutter's pubspec.yaml and
+// a React Native or web app's package.json. Read, never run. Each finding is a suggestion for the spec's gaps, which the
+// partner keeps, rewords or drops in blackbox.hints.json: a package can be listed and never used.
+/** Package name (exact, or a prefix ending in "*") → what the app likely does with it that a web app can't yet. */
+export const KNOWN = [
+    // Flutter (pub.dev)
+    ["workmanager", "background", "Work that runs in the background while the app is closed"],
+    ["background_fetch", "background", "Work that runs in the background while the app is closed"],
+    ["flutter_background_service", "background", "Work that runs in the background while the app is closed"],
+    ["android_alarm_manager_plus", "background", "Alarms that run code while the app is closed"],
+    ["home_widget", "widget", "A home-screen widget"],
+    ["firebase_messaging", "notifications", "Push notifications"],
+    ["flutter_local_notifications", "notifications", "Scheduled notifications"],
+    ["awesome_notifications", "notifications", "Scheduled notifications"],
+    ["onesignal_flutter", "notifications", "Push notifications"],
+    ["in_app_purchase", "purchases", "In-app purchases or subscriptions"],
+    ["purchases_flutter", "purchases", "In-app purchases or subscriptions"],
+    ["firebase_auth", "accounts", "Signing in to an account"],
+    ["google_sign_in", "accounts", "Signing in with Google"],
+    ["sign_in_with_apple", "accounts", "Signing in with Apple"],
+    ["supabase_flutter", "accounts", "Signing in and keeping data on a server"],
+    ["cloud_firestore", "sync", "Data kept on a server and synced across devices"],
+    ["firebase_database", "sync", "Data kept on a server and synced across devices"],
+    ["health", "device", "Reading Apple Health or Health Connect"],
+    ["flutter_blue_plus", "device", "Bluetooth devices beyond what the browser allows"],
+    ["local_auth", "device", "Face ID or fingerprint inside the app"],
+    ["geofence_service", "background", "Reacting to places while the app is closed"],
+    // React Native and web (npm)
+    ["react-native-background-fetch", "background", "Work that runs in the background while the app is closed"],
+    ["react-native-background-actions", "background", "Work that runs in the background while the app is closed"],
+    ["expo-background-fetch", "background", "Work that runs in the background while the app is closed"],
+    ["expo-task-manager", "background", "Work that runs in the background while the app is closed"],
+    ["react-native-widget-extension", "widget", "A home-screen widget"],
+    ["@react-native-firebase/messaging", "notifications", "Push notifications"],
+    ["expo-notifications", "notifications", "Push or scheduled notifications"],
+    ["@notifee/react-native", "notifications", "Scheduled notifications"],
+    ["react-native-iap", "purchases", "In-app purchases or subscriptions"],
+    ["react-native-purchases", "purchases", "In-app purchases or subscriptions"],
+    ["expo-in-app-purchases", "purchases", "In-app purchases or subscriptions"],
+    ["@react-native-firebase/auth", "accounts", "Signing in to an account"],
+    ["expo-auth-session", "accounts", "Signing in to an account"],
+    ["@react-native-firebase/firestore", "sync", "Data kept on a server and synced across devices"],
+    ["react-native-health", "device", "Reading Apple Health"],
+    ["react-native-health-connect", "device", "Reading Health Connect"],
+    ["expo-local-authentication", "device", "Face ID or fingerprint inside the app"],
+];
+const matches = (name, pattern) => (pattern.endsWith("*") ? name.startsWith(pattern.slice(0, -1)) : name === pattern);
+/** The dependency names in a pubspec.yaml (under dependencies only, not dev_dependencies), with their lines. */
+function pubspecDeps(text) {
+    const out = [];
+    let inDeps = false;
+    text.split("\n").forEach((raw, i) => {
+        const line = raw.replace(/#.*$/, "");
+        if (/^\S/.test(line))
+            inDeps = /^dependencies\s*:/.test(line);
+        else if (inDeps) {
+            const m = /^ {2}([a-z0-9_]+)\s*:/.exec(line);
+            if (m)
+                out.push({ name: m[1], line: i + 1 });
+        }
+    });
+    return out;
+}
+/** The dependency names in a package.json (dependencies only), with their lines. */
+function packageDeps(text) {
+    let deps = {};
+    try {
+        deps = JSON.parse(text).dependencies ?? {};
+    }
+    catch {
+        return [];
+    }
+    const lines = text.split("\n");
+    return Object.keys(deps).map((name) => ({ name, line: Math.max(1, lines.findIndex((l) => l.includes(`"${name}"`)) + 1) }));
+}
+/** The gaps a manifest suggests, once each by what, in the order the packages are listed. */
+export function gapsIn(file, text) {
+    const deps = file.endsWith("pubspec.yaml") ? pubspecDeps(text) : file.endsWith("package.json") ? packageDeps(text) : [];
+    const out = [];
+    const seen = new Set();
+    for (const d of deps) {
+        const known = KNOWN.find(([pattern]) => matches(d.name, pattern));
+        if (!known || seen.has(known[2]))
+            continue;
+        seen.add(known[2]);
+        out.push({ kind: known[1], what: known[2], package: d.name, line: d.line });
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcrane/blackbox",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Turns an app's code into a CloudCrane app spec with no code in it, checks it, and builds or previews the app it describes.",
   "keywords": [
     "cloudcrane",
@@ -43,8 +43,8 @@
     "typescript": "~5.9.3",
     "veridic": "^0.14.0",
     "zod": "^3.25.76",
-    "@cloudcrane/app-runtime": "^0.5.0",
-    "@cloudcrane/app-spec": "^0.4.0"
+    "@cloudcrane/app-runtime": "^0.8.0",
+    "@cloudcrane/app-spec": "^0.7.0"
   },
   "devDependencies": {
     "tsx": "4.23.15"