@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/canvas-seed.d.ts

@@ -0,0 +1,58 @@
+import type { Rng } from '@protoyard/core';
+import type { Blueprint } from './schema.ts';
+/**
+ * Seeded canvases for the `json` fields a `canvas` screen stores its boards
+ * in. Without this, the generator's generic `json` value (`{ note }`) is not
+ * a Texuli canvas, so every seeded record would open as a canvas that cannot
+ * be read. Each record gets a small planning board instead: a frame titled
+ * after the record with three sticky notes joined by connectors.
+ *
+ * Plain data in the Texuli canvas format (`texuli-canvas`, formatVersion 1):
+ * this module imports nothing from `@texuli/canvas`, and the canvas screen
+ * still validates every stored value as untrusted before it paints.
+ *
+ * Determinism: only the `rng` passed in, no Faker and no clock.
+ */
+/** Sticky prompts a seeded board picks three of, in this order. */
+export declare const CANVAS_SEED_PROMPTS: readonly ["Goals for this round", "Open questions", "Risks to watch", "Next steps", "Ideas to try", "Decisions so far", "Who to involve", "Dependencies"];
+/** `json` field names that back a canvas screen, by entity name. */
+export declare function canvasFieldsByEntity(blueprint: Pick<Blueprint, 'screens'>): Map<string, Set<string>>;
+/** A small planning board for one record: a titled frame, three stickies, two connectors. */
+export declare function seedCanvas(rng: Rng, title: string): {
+    format: "texuli-canvas";
+    formatVersion: 1;
+    meta: {
+        title: string;
+    };
+    shapes: {
+        id: string;
+        type: "frame";
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        title: string;
+        children: {
+            id: string;
+            type: "sticky";
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+            text: string;
+            color: "green" | "blue" | "yellow" | "pink" | "orange" | "purple";
+        }[];
+    }[];
+    connectors: {
+        id: string;
+        from: {
+            shape: string;
+            anchor: "auto";
+        };
+        to: {
+            shape: string;
+            anchor: "auto";
+        };
+        routing: "curved";
+    }[];
+};

package/dist/canvas-seed.js

@@ -0,0 +1,82 @@
+/**
+ * Seeded canvases for the `json` fields a `canvas` screen stores its boards
+ * in. Without this, the generator's generic `json` value (`{ note }`) is not
+ * a Texuli canvas, so every seeded record would open as a canvas that cannot
+ * be read. Each record gets a small planning board instead: a frame titled
+ * after the record with three sticky notes joined by connectors.
+ *
+ * Plain data in the Texuli canvas format (`texuli-canvas`, formatVersion 1):
+ * this module imports nothing from `@texuli/canvas`, and the canvas screen
+ * still validates every stored value as untrusted before it paints.
+ *
+ * Determinism: only the `rng` passed in, no Faker and no clock.
+ */
+/** Sticky prompts a seeded board picks three of, in this order. */
+export const CANVAS_SEED_PROMPTS = [
+    'Goals for this round',
+    'Open questions',
+    'Risks to watch',
+    'Next steps',
+    'Ideas to try',
+    'Decisions so far',
+    'Who to involve',
+    'Dependencies',
+];
+const STICKY_COLORS = ['yellow', 'green', 'blue', 'pink', 'orange', 'purple'];
+/** Canvas titles are capped at 200 characters, like the screen's blank canvas. */
+const MAX_TITLE = 200;
+/** `json` field names that back a canvas screen, by entity name. */
+export function canvasFieldsByEntity(blueprint) {
+    const byEntity = new Map();
+    for (const screen of blueprint.screens) {
+        if (screen.type !== 'canvas')
+            continue;
+        let fields = byEntity.get(screen.entity);
+        if (!fields) {
+            fields = new Set();
+            byEntity.set(screen.entity, fields);
+        }
+        fields.add(screen.field);
+    }
+    return byEntity;
+}
+/** A small planning board for one record: a titled frame, three stickies, two connectors. */
+export function seedCanvas(rng, title) {
+    const name = title.trim().slice(0, MAX_TITLE) || 'Planning board';
+    const order = rng.sample(CANVAS_SEED_PROMPTS.map((_, index) => index), 3);
+    const prompts = order.sort((a, b) => a - b).map((index) => CANVAS_SEED_PROMPTS[index]);
+    const colors = rng.sample(STICKY_COLORS, 3);
+    const stickies = prompts.map((text, index) => ({
+        id: `seed-sticky-${index + 1}`,
+        type: 'sticky',
+        x: 40 + index * 220,
+        y: 96 + (index % 2) * 24,
+        width: 180,
+        height: 140,
+        text,
+        color: colors[index] ?? 'yellow',
+    }));
+    return {
+        format: 'texuli-canvas',
+        formatVersion: 1,
+        meta: { title: name },
+        shapes: [
+            {
+                id: 'seed-frame',
+                type: 'frame',
+                x: 0,
+                y: 0,
+                width: 720,
+                height: 320,
+                title: name,
+                children: stickies,
+            },
+        ],
+        connectors: stickies.slice(1).map((sticky, index) => ({
+            id: `seed-link-${index + 1}`,
+            from: { shape: stickies[index]?.id, anchor: 'auto' },
+            to: { shape: sticky.id, anchor: 'auto' },
+            routing: 'curved',
+        })),
+    };
+}

package/dist/computed/evaluate.d.ts

@@ -0,0 +1,11 @@
+import type { ComputedEvaluationContext, ComputedValue } from './types.ts';
+import { validateComputedExpression } from './validate.ts';
+export type ComputedEvaluationResult = {
+    success: true;
+    value: ComputedValue;
+} | {
+    success: false;
+    diagnostics: ReturnType<typeof validateComputedExpression>['diagnostics'];
+};
+/** Validate and evaluate a read-only AST. Missing or invalid row values propagate as null. */
+export declare function evaluateComputedExpression(expression: unknown, context: ComputedEvaluationContext): ComputedEvaluationResult;

package/dist/computed/evaluate.js

@@ -0,0 +1,101 @@
+import { validateComputedExpression } from "./validate.js";
+function ownValue(record, key) {
+    return record && Object.hasOwn(record, key) ? record[key] : null;
+}
+function asMilliseconds(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value !== 'string')
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function relatedRows(value) {
+    if (Array.isArray(value))
+        return value.filter(isRecord);
+    return isRecord(value) ? [value] : [];
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function finiteOrNull(value) {
+    return Number.isFinite(value) ? value : null;
+}
+function evaluate(expression, context) {
+    if (expression.op === 'literal')
+        return expression.value;
+    if (expression.op === 'field') {
+        const value = ownValue(context.row, expression.field);
+        if (typeof value === 'string' || typeof value === 'boolean' || value === null)
+            return value;
+        return typeof value === 'number' && Number.isFinite(value) ? value : null;
+    }
+    if (expression.op === 'concat') {
+        const values = expression.values.map((child) => evaluate(child, context));
+        return values.every((value) => typeof value === 'string') ? values.join('') : null;
+    }
+    if (expression.op === 'dateDiff') {
+        const start = asMilliseconds(evaluate(expression.start, context));
+        const end = asMilliseconds(evaluate(expression.end, context));
+        if (start === null || end === null)
+            return null;
+        const divisor = {
+            milliseconds: 1,
+            seconds: 1_000,
+            minutes: 60_000,
+            hours: 3_600_000,
+            days: 86_400_000,
+        }[expression.unit];
+        return finiteOrNull((end - start) / divisor);
+    }
+    if (expression.op === 'aggregate') {
+        const rows = relatedRows(ownValue(context.relations, expression.relation));
+        if (expression.aggregate === 'count')
+            return rows.length;
+        const values = rows
+            .map((row) => ownValue(row, expression.field ?? ''))
+            .filter((value) => value !== null && value !== undefined);
+        if (values.length === 0)
+            return null;
+        if (expression.aggregate === 'min' || expression.aggregate === 'max') {
+            const first = values[0];
+            if (typeof first === 'string') {
+                const dates = values.map(asMilliseconds);
+                if (dates.every((date) => date !== null)) {
+                    const target = dates.reduce((best, date) => expression.aggregate === 'min' ? Math.min(best, date) : Math.max(best, date));
+                    return values.find((value) => asMilliseconds(value) === target);
+                }
+            }
+            const numbers = values.filter((value) => typeof value === 'number' && Number.isFinite(value));
+            if (numbers.length !== values.length)
+                return null;
+            return numbers.reduce((best, number) => expression.aggregate === 'min' ? Math.min(best, number) : Math.max(best, number));
+        }
+        const numbers = values.filter((value) => typeof value === 'number' && Number.isFinite(value));
+        if (numbers.length !== values.length)
+            return null;
+        const sum = numbers.reduce((total, value) => total + value, 0);
+        return expression.aggregate === 'sum' ? finiteOrNull(sum) : finiteOrNull(sum / numbers.length);
+    }
+    const left = evaluate(expression.left, context);
+    const right = evaluate(expression.right, context);
+    if (typeof left !== 'number' || typeof right !== 'number')
+        return null;
+    let value;
+    if (expression.op === 'add')
+        value = left + right;
+    else if (expression.op === 'subtract')
+        value = left - right;
+    else if (expression.op === 'multiply')
+        value = left * right;
+    else
+        value = right === 0 ? Number.NaN : left / right;
+    return Number.isFinite(value) ? value : null;
+}
+/** Validate and evaluate a read-only AST. Missing or invalid row values propagate as null. */
+export function evaluateComputedExpression(expression, context) {
+    const validation = validateComputedExpression(expression, context);
+    if (!validation.valid)
+        return { success: false, diagnostics: validation.diagnostics };
+    return { success: true, value: evaluate(expression, context) };
+}

package/dist/computed/index.d.ts

@@ -0,0 +1,4 @@
+export { type ComputedEvaluationResult, evaluateComputedExpression } from './evaluate.ts';
+export { ComputedExpressionError, MAX_COMPUTED_EXPRESSION_DEPTH, MAX_COMPUTED_EXPRESSION_NODES, parseComputedExpression, safeParseComputedExpression, } from './public.ts';
+export type { ComputedDiagnostic, ComputedEvaluationContext, ComputedExpression, ComputedExpressionContext, ComputedValidationResult, ComputedValue, ComputedValueType, } from './types.ts';
+export { computedContext, validateComputedExpression } from './validate.ts';

package/dist/computed/index.js

@@ -0,0 +1,3 @@
+export { evaluateComputedExpression } from "./evaluate.js";
+export { ComputedExpressionError, MAX_COMPUTED_EXPRESSION_DEPTH, MAX_COMPUTED_EXPRESSION_NODES, parseComputedExpression, safeParseComputedExpression, } from "./public.js";
+export { computedContext, validateComputedExpression } from "./validate.js";

package/dist/computed/public.d.ts

@@ -0,0 +1,14 @@
+import type { ComputedDiagnostic, ComputedExpression } from './types.ts';
+export { MAX_COMPUTED_EXPRESSION_DEPTH, MAX_COMPUTED_EXPRESSION_NODES, } from './schema.ts';
+export declare class ComputedExpressionError extends Error {
+    readonly diagnostics: ComputedDiagnostic[];
+    constructor(diagnostics: ComputedDiagnostic[]);
+}
+export declare function safeParseComputedExpression(input: unknown): {
+    success: true;
+    data: ComputedExpression;
+} | {
+    success: false;
+    diagnostics: ComputedDiagnostic[];
+};
+export declare function parseComputedExpression(input: unknown): ComputedExpression;

package/dist/computed/public.js

@@ -0,0 +1,19 @@
+import { parseExpressionShape } from "./schema.js";
+export { MAX_COMPUTED_EXPRESSION_DEPTH, MAX_COMPUTED_EXPRESSION_NODES, } from "./schema.js";
+export class ComputedExpressionError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        super(diagnostics.map((diagnostic) => `${diagnostic.jsonPath}: ${diagnostic.message}`).join('\n'));
+        this.name = 'ComputedExpressionError';
+        this.diagnostics = diagnostics;
+    }
+}
+export function safeParseComputedExpression(input) {
+    return parseExpressionShape(input);
+}
+export function parseComputedExpression(input) {
+    const result = parseExpressionShape(input);
+    if (!result.success)
+        throw new ComputedExpressionError(result.diagnostics);
+    return result.data;
+}

package/dist/computed/schema.d.ts

@@ -0,0 +1,10 @@
+import type { ComputedDiagnostic, ComputedExpression } from './types.ts';
+export declare const MAX_COMPUTED_EXPRESSION_DEPTH = 32;
+export declare const MAX_COMPUTED_EXPRESSION_NODES = 256;
+export declare function parseExpressionShape(input: unknown): {
+    success: true;
+    data: ComputedExpression;
+} | {
+    success: false;
+    diagnostics: ComputedDiagnostic[];
+};

package/dist/computed/schema.js

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+export const MAX_COMPUTED_EXPRESSION_DEPTH = 32;
+export const MAX_COMPUTED_EXPRESSION_NODES = 256;
+const fieldName = z.string().regex(/^[a-z][a-zA-Z0-9]*$/, {
+    message: 'field references must use lowerCamelCase names',
+});
+const scalar = z.union([z.string().max(1_000), z.number().finite(), z.boolean(), z.null()]);
+const ExpressionSchema = z.lazy(() => z.discriminatedUnion('op', [
+    z.strictObject({ op: z.literal('literal'), value: scalar }),
+    z.strictObject({ op: z.literal('field'), field: fieldName }),
+    ...['add', 'subtract', 'multiply', 'divide'].map((op) => z.strictObject({ op: z.literal(op), left: ExpressionSchema, right: ExpressionSchema })),
+    z.strictObject({ op: z.literal('concat'), values: z.array(ExpressionSchema).min(2).max(32) }),
+    z.strictObject({
+        op: z.literal('dateDiff'),
+        start: ExpressionSchema,
+        end: ExpressionSchema,
+        unit: z.enum(['milliseconds', 'seconds', 'minutes', 'hours', 'days']),
+    }),
+    z.strictObject({
+        op: z.literal('aggregate'),
+        relation: fieldName,
+        aggregate: z.enum(['count', 'sum', 'avg', 'min', 'max']),
+        field: fieldName.optional(),
+    }),
+]));
+/** Reject non-JSON containers, cycles and excessive AST size before recursive Zod parsing. */
+function preflight(input) {
+    const seen = new WeakSet();
+    const stack = [
+        { value: input, depth: 1, path: [] },
+    ];
+    let nodes = 0;
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const value = current.value;
+        if (value === null || typeof value !== 'object')
+            continue;
+        if (seen.has(value)) {
+            return {
+                code: 'cyclic-expression',
+                path: current.path,
+                message: 'expression data must not contain cycles',
+            };
+        }
+        seen.add(value);
+        nodes += 1;
+        if (nodes > MAX_COMPUTED_EXPRESSION_NODES) {
+            return {
+                code: 'expression-too-large',
+                path: current.path,
+                message: `expression exceeds ${MAX_COMPUTED_EXPRESSION_NODES} object or array nodes`,
+            };
+        }
+        if (current.depth > MAX_COMPUTED_EXPRESSION_DEPTH) {
+            return {
+                code: 'expression-too-deep',
+                path: current.path,
+                message: `expression exceeds depth ${MAX_COMPUTED_EXPRESSION_DEPTH}`,
+            };
+        }
+        if (Array.isArray(value)) {
+            if (value.length > MAX_COMPUTED_EXPRESSION_NODES) {
+                return {
+                    code: 'expression-too-large',
+                    path: current.path,
+                    message: `expression array exceeds ${MAX_COMPUTED_EXPRESSION_NODES} entries`,
+                };
+            }
+            for (let index = value.length - 1; index >= 0; index -= 1) {
+                stack.push({
+                    value: value[index],
+                    depth: current.depth + 1,
+                    path: [...current.path, index],
+                });
+            }
+            continue;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return {
+                code: 'invalid-container',
+                path: current.path,
+                message: 'expression objects must be plain JSON objects',
+            };
+        }
+        const keys = Object.keys(value);
+        if (keys.length > MAX_COMPUTED_EXPRESSION_NODES) {
+            return {
+                code: 'expression-too-large',
+                path: current.path,
+                message: `expression object exceeds ${MAX_COMPUTED_EXPRESSION_NODES} properties`,
+            };
+        }
+        for (const key of keys.reverse()) {
+            stack.push({
+                value: value[key],
+                depth: current.depth + 1,
+                path: [...current.path, key],
+            });
+        }
+    }
+    return null;
+}
+function jsonPath(path) {
+    let result = '$';
+    for (const segment of path) {
+        result += typeof segment === 'number' ? `[${segment}]` : `[${JSON.stringify(segment)}]`;
+    }
+    return result;
+}
+export function parseExpressionShape(input) {
+    const sizeFailure = preflight(input);
+    if (sizeFailure) {
+        return {
+            success: false,
+            diagnostics: [
+                {
+                    ...sizeFailure,
+                    jsonPath: jsonPath(sizeFailure.path),
+                    hint: 'Simplify the expression and use only bounded JSON expression nodes.',
+                },
+            ],
+        };
+    }
+    const result = ExpressionSchema.safeParse(input);
+    if (result.success)
+        return { success: true, data: result.data };
+    return {
+        success: false,
+        diagnostics: result.error.issues.map((issue) => ({
+            code: `schema-${issue.code}`,
+            path: issue.path.filter((segment) => typeof segment !== 'symbol'),
+            jsonPath: jsonPath(issue.path.filter((segment) => typeof segment !== 'symbol')),
+            message: issue.message,
+            hint: 'Use the documented expression operator and its required fields; executable strings are not expressions.',
+        })),
+    };
+}

package/dist/computed/types.d.ts

@@ -0,0 +1,70 @@
+/** The closed JSON AST used for deterministic, read-time computed values. */
+export type ComputedExpression = {
+    op: 'literal';
+    value: string | number | boolean | null;
+} | {
+    op: 'field';
+    field: string;
+} | {
+    op: 'add' | 'subtract' | 'multiply' | 'divide';
+    left: ComputedExpression;
+    right: ComputedExpression;
+} | {
+    op: 'concat';
+    values: ComputedExpression[];
+} | {
+    op: 'dateDiff';
+    start: ComputedExpression;
+    end: ComputedExpression;
+    unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days';
+} | {
+    op: 'aggregate';
+    relation: string;
+    aggregate: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    field?: string;
+};
+/** Static types supported by computed expressions. */
+export type ComputedValueType = 'number' | 'string' | 'boolean' | 'date' | 'null';
+/** JSON-compatible computed result; missing input values propagate as null. */
+export type ComputedValue = string | number | boolean | null;
+export type ComputedDiagnostic = {
+    code: string;
+    path: (string | number)[];
+    jsonPath: string;
+    message: string;
+    hint: string;
+};
+export type ComputedExpressionContext = {
+    /** Entity whose row is passed to field expressions. */
+    sourceEntity: {
+        name: string;
+        fields: readonly {
+            name: string;
+            kind: string;
+            required?: boolean;
+            to?: string;
+        }[];
+    };
+    /** All blueprint entities, used to resolve relation targets. */
+    entities: readonly {
+        name: string;
+        fields: readonly {
+            name: string;
+            kind: string;
+            required?: boolean;
+            to?: string;
+        }[];
+    }[];
+};
+export type ComputedValidationResult = {
+    valid: boolean;
+    diagnostics: ComputedDiagnostic[];
+    resultType: ComputedValueType | null;
+    nullable: boolean;
+};
+export type ComputedEvaluationContext = ComputedExpressionContext & {
+    /** Current entity row. Values are read only and never mutated. */
+    row: Readonly<Record<string, unknown>>;
+    /** Related records grouped by relation field name; many relations use arrays. */
+    relations?: Readonly<Record<string, unknown>>;
+};

package/dist/computed/types.js

@@ -0,0 +1 @@
+export {};

package/dist/computed/validate.d.ts

@@ -0,0 +1,6 @@
+import type { BlueprintEntity } from '../schema.ts';
+import type { ComputedExpressionContext, ComputedValidationResult } from './types.ts';
+/** Validate AST shape, field references, operator input types and inferred output type. */
+export declare function validateComputedExpression(input: unknown, context: ComputedExpressionContext): ComputedValidationResult;
+/** Helper for callers that need to use the public entity shape as context. */
+export declare function computedContext(sourceEntity: BlueprintEntity, entities: readonly BlueprintEntity[]): ComputedExpressionContext;