mirror of
https://github.com/hypit-ai/hypit.git
synced 2026-11-21 20:50:44 +00:00
4d1ac02104
Extract renderer-neutral local HTML execution, keep Chromium and Electron backends independent, bound Producer inline values, and harden public diagnostics and text handling.
559 lines
20 KiB
TypeScript
559 lines
20 KiB
TypeScript
import { canonicalize } from "@hypit/protocol";
|
|
|
|
import type {
|
|
Text,
|
|
TextBinding,
|
|
TextBindings,
|
|
TextBindingValue,
|
|
TextCondition,
|
|
TextExpression,
|
|
TextScalar,
|
|
TextTemplate,
|
|
TextTransform,
|
|
} from "./types.js";
|
|
|
|
const NAME = /^[a-z][a-z0-9-]{0,95}$/u;
|
|
|
|
function assert(condition: unknown, message: string): asserts condition {
|
|
if (!condition) throw new Error(message);
|
|
}
|
|
|
|
function object(value: unknown, subject: string): Record<string, unknown> {
|
|
assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
|
|
return value as Record<string, unknown>;
|
|
}
|
|
|
|
function name(value: unknown, subject: string): asserts value is string {
|
|
assert(typeof value === "string" && NAME.test(value), `${subject} must be a lower-kebab name`);
|
|
}
|
|
|
|
function scalar(value: unknown, subject: string): asserts value is TextScalar {
|
|
assert(
|
|
typeof value === "string"
|
|
|| typeof value === "boolean"
|
|
|| (typeof value === "number" && Number.isFinite(value)),
|
|
`${subject} must be text, boolean or a finite number`,
|
|
);
|
|
}
|
|
|
|
function bindingValue(value: unknown, subject: string): asserts value is TextBindingValue {
|
|
if (!Array.isArray(value)) {
|
|
scalar(value, subject);
|
|
return;
|
|
}
|
|
value.forEach((item, index) => scalar(item, `${subject}[${index}]`));
|
|
}
|
|
|
|
function condition(value: unknown, subject: string): asserts value is TextCondition {
|
|
const item = object(value, subject);
|
|
if (item.kind === "present") {
|
|
name(item.binding, `${subject}.binding`);
|
|
return;
|
|
}
|
|
if (item.kind === "equals") {
|
|
name(item.binding, `${subject}.binding`);
|
|
scalar(item.value, `${subject}.value`);
|
|
return;
|
|
}
|
|
if (item.kind === "all" || item.kind === "any") {
|
|
assert(Array.isArray(item.conditions) && item.conditions.length > 0, `${subject}.conditions must be non-empty`);
|
|
item.conditions.forEach((entry, index) => condition(entry, `${subject}.conditions[${index}]`));
|
|
return;
|
|
}
|
|
if (item.kind === "not") {
|
|
condition(item.condition, `${subject}.condition`);
|
|
return;
|
|
}
|
|
throw new Error(`${subject}.kind is invalid`);
|
|
}
|
|
|
|
function transform(value: unknown, subject: string): asserts value is TextTransform {
|
|
const item = object(value, subject);
|
|
assert(
|
|
item.kind === "trim"
|
|
|| item.kind === "trim-start"
|
|
|| item.kind === "trim-end"
|
|
|| item.kind === "uppercase"
|
|
|| item.kind === "lowercase"
|
|
|| item.kind === "collapse-whitespace"
|
|
|| item.kind === "normalize-newlines"
|
|
|| item.kind === "json-string",
|
|
`${subject}.kind is invalid`,
|
|
);
|
|
}
|
|
|
|
function expression(
|
|
value: unknown,
|
|
subject: string,
|
|
calls: Set<string>,
|
|
): asserts value is TextExpression {
|
|
const item = object(value, subject);
|
|
if (item.kind === "literal") {
|
|
assert(typeof item.value === "string", `${subject}.value must be text`);
|
|
return;
|
|
}
|
|
if (item.kind === "slot") {
|
|
name(item.binding, `${subject}.binding`);
|
|
return;
|
|
}
|
|
if (item.kind === "sequence" || item.kind === "join") {
|
|
assert(Array.isArray(item.items), `${subject}.items must be an array`);
|
|
if (item.kind === "join") {
|
|
assert(typeof item.separator === "string", `${subject}.separator must be text`);
|
|
assert(item.omitEmpty === undefined || typeof item.omitEmpty === "boolean", `${subject}.omitEmpty must be boolean`);
|
|
}
|
|
item.items.forEach((entry, index) => expression(entry, `${subject}.items[${index}]`, calls));
|
|
return;
|
|
}
|
|
if (item.kind === "choice") {
|
|
assert(Array.isArray(item.cases) && item.cases.length > 0, `${subject}.cases must be non-empty`);
|
|
item.cases.forEach((entry, index) => {
|
|
const candidate = object(entry, `${subject}.cases[${index}]`);
|
|
condition(candidate.when, `${subject}.cases[${index}].when`);
|
|
expression(candidate.value, `${subject}.cases[${index}].value`, calls);
|
|
});
|
|
if (item.otherwise !== undefined) expression(item.otherwise, `${subject}.otherwise`, calls);
|
|
return;
|
|
}
|
|
if (item.kind === "optional") {
|
|
condition(item.when, `${subject}.when`);
|
|
expression(item.value, `${subject}.value`, calls);
|
|
return;
|
|
}
|
|
if (item.kind === "each") {
|
|
name(item.binding, `${subject}.binding`);
|
|
name(item.as, `${subject}.as`);
|
|
assert(typeof item.separator === "string", `${subject}.separator must be text`);
|
|
expression(item.value, `${subject}.value`, calls);
|
|
return;
|
|
}
|
|
if (item.kind === "replace") {
|
|
expression(item.input, `${subject}.input`, calls);
|
|
assert(Array.isArray(item.replacements), `${subject}.replacements must be an array`);
|
|
item.replacements.forEach((entry, index) => {
|
|
const replacement = object(entry, `${subject}.replacements[${index}]`);
|
|
assert(typeof replacement.from === "string" && replacement.from.length > 0,
|
|
`${subject}.replacements[${index}].from must be non-empty text`);
|
|
assert(typeof replacement.to === "string", `${subject}.replacements[${index}].to must be text`);
|
|
assert(replacement.mode === "first" || replacement.mode === "all",
|
|
`${subject}.replacements[${index}].mode is invalid`);
|
|
});
|
|
return;
|
|
}
|
|
if (item.kind === "transform") {
|
|
expression(item.input, `${subject}.input`, calls);
|
|
assert(Array.isArray(item.transforms) && item.transforms.length > 0, `${subject}.transforms must be non-empty`);
|
|
item.transforms.forEach((entry, index) => transform(entry, `${subject}.transforms[${index}]`));
|
|
return;
|
|
}
|
|
if (item.kind === "call") {
|
|
name(item.template, `${subject}.template`);
|
|
calls.add(item.template);
|
|
return;
|
|
}
|
|
throw new Error(`${subject}.kind is invalid`);
|
|
}
|
|
|
|
function callGraph(template: TextTemplate): Map<string, Set<string>> {
|
|
const graph = new Map<string, Set<string>>();
|
|
const rootCalls = new Set<string>();
|
|
expression(template.root, "TextTemplate.root", rootCalls);
|
|
graph.set("$root", rootCalls);
|
|
for (const [id, value] of Object.entries(template.definitions ?? {})) {
|
|
name(id, `TextTemplate.definitions key ${id}`);
|
|
const calls = new Set<string>();
|
|
expression(value, `TextTemplate.definitions.${id}`, calls);
|
|
graph.set(id, calls);
|
|
}
|
|
return graph;
|
|
}
|
|
|
|
function verifyFiniteCalls(template: TextTemplate): void {
|
|
const graph = callGraph(template);
|
|
for (const [from, calls] of graph) {
|
|
for (const target of calls) {
|
|
assert(graph.has(target), `TextTemplate ${from} calls unknown definition ${target}`);
|
|
}
|
|
}
|
|
const visiting = new Set<string>();
|
|
const visited = new Set<string>();
|
|
const visit = (id: string) => {
|
|
if (visited.has(id)) return;
|
|
assert(!visiting.has(id), `TextTemplate call cycle reaches ${id}`);
|
|
visiting.add(id);
|
|
for (const target of graph.get(id) ?? []) visit(target);
|
|
visiting.delete(id);
|
|
visited.add(id);
|
|
};
|
|
visit("$root");
|
|
for (const id of graph.keys()) visit(id);
|
|
}
|
|
|
|
export function verifyText(value: unknown): asserts value is Text {
|
|
const item = object(value, "Text");
|
|
assert(typeof item.value === "string", "Text is invalid");
|
|
}
|
|
|
|
export function sealText(value: string): Text {
|
|
const result = canonicalize({ value }) as unknown as Text;
|
|
verifyText(result);
|
|
return result;
|
|
}
|
|
|
|
export function verifyTextBindings(value: unknown): asserts value is TextBindings {
|
|
const item = object(value, "TextBindings");
|
|
const values = object(item.values, "TextBindings.values");
|
|
for (const [id, entry] of Object.entries(values)) {
|
|
name(id, `TextBindings.values key ${id}`);
|
|
bindingValue(entry, `TextBindings.values.${id}`);
|
|
}
|
|
}
|
|
|
|
export function sealTextBindings(values: Readonly<Record<string, TextBindingValue>> = {}): TextBindings {
|
|
const result = canonicalize({ values }) as unknown as TextBindings;
|
|
verifyTextBindings(result);
|
|
return result;
|
|
}
|
|
|
|
export function verifyTextBinding(value: unknown): asserts value is TextBinding {
|
|
const item = object(value, "TextBinding");
|
|
name(item.name, "TextBinding.name");
|
|
assert(item.mode === "set" || item.mode === "append", "TextBinding.mode is invalid");
|
|
}
|
|
|
|
export function sealTextBinding(value: TextBinding): TextBinding {
|
|
const result = canonicalize({ ...value }) as unknown as TextBinding;
|
|
verifyTextBinding(result);
|
|
return result;
|
|
}
|
|
|
|
export function bindText(
|
|
bindings: TextBindings,
|
|
binding: TextBinding,
|
|
text: Text,
|
|
): TextBindings {
|
|
verifyTextBindings(bindings);
|
|
verifyTextBinding(binding);
|
|
verifyText(text);
|
|
const existing = bindings.values[binding.name];
|
|
if (binding.mode === "set") {
|
|
assert(existing === undefined, `Text binding ${binding.name} is already set`);
|
|
return sealTextBindings({ ...bindings.values, [binding.name]: text.value });
|
|
}
|
|
if (existing === undefined) return sealTextBindings({ ...bindings.values, [binding.name]: [text.value] });
|
|
const values = Array.isArray(existing) ? [...existing] : [existing];
|
|
return sealTextBindings({ ...bindings.values, [binding.name]: [...values, text.value] });
|
|
}
|
|
|
|
export function verifyTextTemplate(value: unknown): asserts value is TextTemplate {
|
|
const template = object(value, "TextTemplate") as unknown as TextTemplate;
|
|
if (template.defaults !== undefined) {
|
|
const defaults = object(template.defaults, "TextTemplate.defaults");
|
|
for (const [id, entry] of Object.entries(defaults)) {
|
|
name(id, `TextTemplate.defaults key ${id}`);
|
|
bindingValue(entry, `TextTemplate.defaults.${id}`);
|
|
}
|
|
}
|
|
if (template.definitions !== undefined) object(template.definitions, "TextTemplate.definitions");
|
|
verifyFiniteCalls(template);
|
|
}
|
|
|
|
export function sealTextTemplate(value: TextTemplate): TextTemplate {
|
|
const result = canonicalize(value) as unknown as TextTemplate;
|
|
verifyTextTemplate(result);
|
|
return result;
|
|
}
|
|
|
|
function collectBindings(
|
|
value: TextExpression,
|
|
template: TextTemplate,
|
|
result: Set<string>,
|
|
locals: ReadonlySet<string>,
|
|
definitions: Map<TextExpression, Map<string, readonly string[]>>,
|
|
): void {
|
|
const add = (id: string) => { if (!locals.has(id)) result.add(id); };
|
|
const collectCondition = (item: TextCondition): void => {
|
|
if (item.kind === "present" || item.kind === "equals") {
|
|
add(item.binding);
|
|
return;
|
|
}
|
|
if (item.kind === "all" || item.kind === "any") {
|
|
item.conditions.forEach(collectCondition);
|
|
return;
|
|
}
|
|
collectCondition(item.condition);
|
|
};
|
|
if (value.kind === "literal") return;
|
|
if (value.kind === "slot") {
|
|
add(value.binding);
|
|
return;
|
|
}
|
|
if (value.kind === "sequence" || value.kind === "join") {
|
|
value.items.forEach((item) => collectBindings(item, template, result, locals, definitions));
|
|
return;
|
|
}
|
|
if (value.kind === "choice") {
|
|
value.cases.forEach((item) => {
|
|
collectCondition(item.when);
|
|
collectBindings(item.value, template, result, locals, definitions);
|
|
});
|
|
if (value.otherwise !== undefined) collectBindings(value.otherwise, template, result, locals, definitions);
|
|
return;
|
|
}
|
|
if (value.kind === "optional") {
|
|
collectCondition(value.when);
|
|
collectBindings(value.value, template, result, locals, definitions);
|
|
return;
|
|
}
|
|
if (value.kind === "each") {
|
|
add(value.binding);
|
|
collectBindings(value.value, template, result, new Set([...locals, value.as]), definitions);
|
|
return;
|
|
}
|
|
if (value.kind === "replace" || value.kind === "transform") {
|
|
collectBindings(value.input, template, result, locals, definitions);
|
|
return;
|
|
}
|
|
const definition = template.definitions?.[value.template];
|
|
if (definition === undefined) return;
|
|
const scope = JSON.stringify([...locals].sort());
|
|
const cached = definitions.get(definition)?.get(scope);
|
|
if (cached !== undefined) {
|
|
cached.forEach((id) => result.add(id));
|
|
return;
|
|
}
|
|
const contributed = new Set<string>();
|
|
collectBindings(definition, template, contributed, locals, definitions);
|
|
let scopes = definitions.get(definition);
|
|
if (scopes === undefined) {
|
|
scopes = new Map();
|
|
definitions.set(definition, scopes);
|
|
}
|
|
scopes.set(scope, [...contributed]);
|
|
contributed.forEach((id) => result.add(id));
|
|
}
|
|
|
|
export function textTemplateBindingNames(template: TextTemplate): ReadonlySet<string> {
|
|
verifyTextTemplate(template);
|
|
const result = new Set<string>();
|
|
collectBindings(template.root, template, result, new Set(), new Map());
|
|
return result;
|
|
}
|
|
|
|
function hasBinding(bindings: Readonly<Record<string, TextBindingValue>>, id: string): boolean {
|
|
const value = bindings[id];
|
|
return value !== undefined && (!Array.isArray(value) || value.length > 0);
|
|
}
|
|
|
|
function matches(value: TextCondition, bindings: Readonly<Record<string, TextBindingValue>>): boolean {
|
|
if (value.kind === "present") return hasBinding(bindings, value.binding);
|
|
if (value.kind === "equals") {
|
|
const actual = bindings[value.binding];
|
|
return !Array.isArray(actual) && actual === value.value;
|
|
}
|
|
if (value.kind === "all") return value.conditions.every((item) => matches(item, bindings));
|
|
if (value.kind === "any") return value.conditions.some((item) => matches(item, bindings));
|
|
return !matches(value.condition, bindings);
|
|
}
|
|
|
|
function scalarText(value: TextBindingValue | undefined, subject: string): string {
|
|
assert(value !== undefined, `${subject} is missing`);
|
|
assert(!Array.isArray(value), `${subject} is a list and must be consumed by each`);
|
|
return String(value);
|
|
}
|
|
|
|
function applyTransform(value: string, operation: TextTransform): string {
|
|
if (operation.kind === "trim") return value.trim();
|
|
if (operation.kind === "trim-start") return value.trimStart();
|
|
if (operation.kind === "trim-end") return value.trimEnd();
|
|
if (operation.kind === "uppercase") return value.toUpperCase();
|
|
if (operation.kind === "lowercase") return value.toLowerCase();
|
|
if (operation.kind === "collapse-whitespace") return value.replace(/\s+/gu, " ").trim();
|
|
if (operation.kind === "normalize-newlines") return value.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
|
|
return JSON.stringify(value);
|
|
}
|
|
|
|
export type TextRenderOptions = {
|
|
/** Limit for the canonical `{ value: string }` returned by this render. */
|
|
readonly maxInlineValueBytes?: number;
|
|
};
|
|
|
|
type TextRenderBuffer = {
|
|
readonly chunks: string[];
|
|
readonly maxInlineValueBytes: number | undefined;
|
|
escapedBytes: number;
|
|
pendingHighSurrogate: boolean;
|
|
};
|
|
|
|
const textValueJsonOverhead = Buffer.byteLength('{"value":""}', "utf8");
|
|
|
|
function createTextRenderBuffer(maxInlineValueBytes: number | undefined): TextRenderBuffer {
|
|
if (maxInlineValueBytes !== undefined) {
|
|
assert(Number.isSafeInteger(maxInlineValueBytes) && maxInlineValueBytes > 0,
|
|
"Text render maxInlineValueBytes must be a positive safe integer");
|
|
assert(maxInlineValueBytes >= textValueJsonOverhead,
|
|
`Text render inline Value limit ${maxInlineValueBytes} bytes cannot contain an empty Text value`);
|
|
}
|
|
return { chunks: [], maxInlineValueBytes, escapedBytes: 0, pendingHighSurrogate: false };
|
|
}
|
|
|
|
function escapedCodeUnitBytes(value: number): number {
|
|
if (value === 0x22 || value === 0x5c || value === 0x08 || value === 0x09
|
|
|| value === 0x0a || value === 0x0c || value === 0x0d) return 2;
|
|
if (value < 0x20 || (value >= 0xdc00 && value <= 0xdfff)) return 6;
|
|
if (value <= 0x7f) return 1;
|
|
if (value <= 0x7ff) return 2;
|
|
return 3;
|
|
}
|
|
|
|
function assertTextRenderBudget(output: TextRenderBuffer, final: boolean): void {
|
|
const bytes = textValueJsonOverhead + output.escapedBytes
|
|
+ (output.pendingHighSurrogate ? (final ? 6 : 4) : 0);
|
|
if (output.maxInlineValueBytes !== undefined) {
|
|
assert(bytes <= output.maxInlineValueBytes,
|
|
`Text render exceeds the ${output.maxInlineValueBytes}-byte inline Value limit`);
|
|
}
|
|
}
|
|
|
|
function countRendered(output: TextRenderBuffer, value: string): void {
|
|
for (let index = 0; index < value.length; index += 1) {
|
|
const unit = value.charCodeAt(index);
|
|
if (output.pendingHighSurrogate) {
|
|
if (unit >= 0xdc00 && unit <= 0xdfff) {
|
|
output.escapedBytes += 4;
|
|
output.pendingHighSurrogate = false;
|
|
continue;
|
|
}
|
|
output.escapedBytes += 6;
|
|
output.pendingHighSurrogate = false;
|
|
}
|
|
if (unit >= 0xd800 && unit <= 0xdbff) output.pendingHighSurrogate = true;
|
|
else output.escapedBytes += escapedCodeUnitBytes(unit);
|
|
}
|
|
assertTextRenderBudget(output, false);
|
|
}
|
|
|
|
function appendRendered(output: TextRenderBuffer, value: string): void {
|
|
if (value.length === 0) return;
|
|
countRendered(output, value);
|
|
output.chunks.push(value);
|
|
}
|
|
|
|
function renderExpressionValue(
|
|
value: TextExpression,
|
|
template: TextTemplate,
|
|
bindings: Readonly<Record<string, TextBindingValue>>,
|
|
maxInlineValueBytes?: number,
|
|
): string {
|
|
const output = createTextRenderBuffer(maxInlineValueBytes);
|
|
renderExpression(value, template, bindings, output);
|
|
assertTextRenderBudget(output, true);
|
|
return output.chunks.join("");
|
|
}
|
|
|
|
function replaceLiteral(value: string, from: string, to: string, all: boolean, maxInlineValueBytes?: number): string {
|
|
const output = createTextRenderBuffer(maxInlineValueBytes);
|
|
let cursor = 0;
|
|
while (cursor <= value.length) {
|
|
const found = value.indexOf(from, cursor);
|
|
if (found < 0) {
|
|
appendRendered(output, value.slice(cursor));
|
|
break;
|
|
}
|
|
appendRendered(output, value.slice(cursor, found));
|
|
appendRendered(output, to);
|
|
cursor = found + from.length;
|
|
if (!all) {
|
|
appendRendered(output, value.slice(cursor));
|
|
break;
|
|
}
|
|
}
|
|
assertTextRenderBudget(output, true);
|
|
return output.chunks.join("");
|
|
}
|
|
|
|
function renderExpression(
|
|
value: TextExpression,
|
|
template: TextTemplate,
|
|
bindings: Readonly<Record<string, TextBindingValue>>,
|
|
output: TextRenderBuffer,
|
|
): void {
|
|
if (value.kind === "literal") { appendRendered(output, value.value); return; }
|
|
if (value.kind === "slot") {
|
|
appendRendered(output, scalarText(bindings[value.binding], `Text binding ${value.binding}`));
|
|
return;
|
|
}
|
|
if (value.kind === "sequence") {
|
|
value.items.forEach((item) => renderExpression(item, template, bindings, output));
|
|
return;
|
|
}
|
|
if (value.kind === "join") {
|
|
let written = false;
|
|
for (const item of value.items) {
|
|
const rendered = renderExpressionValue(item, template, bindings, output.maxInlineValueBytes);
|
|
if (value.omitEmpty === true && rendered.length === 0) continue;
|
|
if (written) appendRendered(output, value.separator);
|
|
appendRendered(output, rendered);
|
|
written = true;
|
|
}
|
|
return;
|
|
}
|
|
if (value.kind === "choice") {
|
|
const selected = value.cases.filter((item) => matches(item.when, bindings));
|
|
assert(selected.length <= 1, `Text choice matched ${selected.length} cases`);
|
|
if (selected.length === 1) {
|
|
renderExpression(selected[0]!.value, template, bindings, output);
|
|
return;
|
|
}
|
|
assert(value.otherwise !== undefined, "Text choice matched no case and has no otherwise branch");
|
|
renderExpression(value.otherwise, template, bindings, output);
|
|
return;
|
|
}
|
|
if (value.kind === "optional") {
|
|
if (matches(value.when, bindings)) renderExpression(value.value, template, bindings, output);
|
|
return;
|
|
}
|
|
if (value.kind === "each") {
|
|
const source = bindings[value.binding];
|
|
assert(Array.isArray(source), `Text binding ${value.binding} must be a list`);
|
|
source.forEach((item, index) => {
|
|
if (index > 0) appendRendered(output, value.separator);
|
|
renderExpression(value.value, template, { ...bindings, [value.as]: item }, output);
|
|
});
|
|
return;
|
|
}
|
|
if (value.kind === "replace") {
|
|
let result = renderExpressionValue(value.input, template, bindings, output.maxInlineValueBytes);
|
|
for (const replacement of value.replacements) {
|
|
result = replaceLiteral(result, replacement.from, replacement.to, replacement.mode === "all", output.maxInlineValueBytes);
|
|
}
|
|
appendRendered(output, result);
|
|
return;
|
|
}
|
|
if (value.kind === "transform") {
|
|
const result = value.transforms.reduce(
|
|
(result, operation) => applyTransform(result, operation),
|
|
renderExpressionValue(value.input, template, bindings, output.maxInlineValueBytes),
|
|
);
|
|
appendRendered(output, result);
|
|
return;
|
|
}
|
|
const definition = template.definitions?.[value.template];
|
|
assert(definition !== undefined, `TextTemplate definition ${value.template} is missing`);
|
|
renderExpression(definition, template, bindings, output);
|
|
}
|
|
|
|
export function renderText(template: TextTemplate, bindings: TextBindings, options: TextRenderOptions = {}): Text {
|
|
verifyTextTemplate(template);
|
|
verifyTextBindings(bindings);
|
|
const known = textTemplateBindingNames(template);
|
|
for (const id of Object.keys(template.defaults ?? {})) {
|
|
assert(known.has(id), `TextTemplate default ${id} is not consumed`);
|
|
}
|
|
for (const id of Object.keys(bindings.values)) {
|
|
assert(known.has(id), `Text binding ${id} is not declared by the template`);
|
|
}
|
|
return sealText(renderExpressionValue(template.root, template, { ...template.defaults, ...bindings.values },
|
|
options.maxInlineValueBytes));
|
|
}
|