@hypit/hypit 0.0.1 → 0.1.1

package/packages/text/src/program.ts

@@ -0,0 +1,418 @@
+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>,
+): 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));
+    return;
+  }
+  if (value.kind === "choice") {
+    value.cases.forEach((item) => {
+      collectCondition(item.when);
+      collectBindings(item.value, template, result, locals);
+    });
+    if (value.otherwise !== undefined) collectBindings(value.otherwise, template, result, locals);
+    return;
+  }
+  if (value.kind === "optional") {
+    collectCondition(value.when);
+    collectBindings(value.value, template, result, locals);
+    return;
+  }
+  if (value.kind === "each") {
+    add(value.binding);
+    collectBindings(value.value, template, result, new Set([...locals, value.as]));
+    return;
+  }
+  if (value.kind === "replace" || value.kind === "transform") {
+    collectBindings(value.input, template, result, locals);
+    return;
+  }
+  const definition = template.definitions?.[value.template];
+  if (definition !== undefined) collectBindings(definition, template, result, locals);
+}
+
+export function textTemplateBindingNames(template: TextTemplate): ReadonlySet<string> {
+  verifyTextTemplate(template);
+  const result = new Set<string>();
+  collectBindings(template.root, template, result, new Set());
+  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);
+}
+
+function renderExpression(
+  value: TextExpression,
+  template: TextTemplate,
+  bindings: Readonly<Record<string, TextBindingValue>>,
+): string {
+  if (value.kind === "literal") return value.value;
+  if (value.kind === "slot") return scalarText(bindings[value.binding], `Text binding ${value.binding}`);
+  if (value.kind === "sequence") return value.items.map((item) => renderExpression(item, template, bindings)).join("");
+  if (value.kind === "join") {
+    const items = value.items.map((item) => renderExpression(item, template, bindings));
+    return (value.omitEmpty === true ? items.filter((item) => item.length > 0) : items).join(value.separator);
+  }
+  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) return renderExpression(selected[0]!.value, template, bindings);
+    assert(value.otherwise !== undefined, "Text choice matched no case and has no otherwise branch");
+    return renderExpression(value.otherwise, template, bindings);
+  }
+  if (value.kind === "optional") {
+    return matches(value.when, bindings) ? renderExpression(value.value, template, bindings) : "";
+  }
+  if (value.kind === "each") {
+    const source = bindings[value.binding];
+    assert(Array.isArray(source), `Text binding ${value.binding} must be a list`);
+    return source.map((item) => renderExpression(value.value, template, { ...bindings, [value.as]: item })).join(value.separator);
+  }
+  if (value.kind === "replace") {
+    let result = renderExpression(value.input, template, bindings);
+    for (const replacement of value.replacements) {
+      result = replacement.mode === "all"
+        ? result.replaceAll(replacement.from, replacement.to)
+        : result.replace(replacement.from, replacement.to);
+    }
+    return result;
+  }
+  if (value.kind === "transform") {
+    return value.transforms.reduce(
+      (result, operation) => applyTransform(result, operation),
+      renderExpression(value.input, template, bindings),
+    );
+  }
+  const definition = template.definitions?.[value.template];
+  assert(definition !== undefined, `TextTemplate definition ${value.template} is missing`);
+  return renderExpression(definition, template, bindings);
+}
+
+export function renderText(template: TextTemplate, bindings: TextBindings): 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(renderExpression(template.root, template, { ...template.defaults, ...bindings.values }));
+}

package/packages/text/src/surface.ts

@@ -0,0 +1,212 @@
+import type { CanonicalValue } from "@hypit/protocol";
+import { svsRecipeType } from "@hypit/svs";
+import type { SvsRecipe } from "@hypit/svs";
+import type {
+  MarkupAttributeValue,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+} from "@hypit/markup";
+
+import { createTextRenderFragment } from "./fragment.js";
+import {
+  sealText,
+  sealTextBinding,
+  sealTextBindings,
+  textTemplateBindingNames,
+  verifyTextTemplate,
+} from "./program.js";
+import { textTypes } from "./manifest.js";
+import type { TextBindingValue, TextScalar, TextTemplate } from "./types.js";
+
+function localName(value: string): string {
+  return value.includes(":") ? value.slice(value.lastIndexOf(":") + 1) : value;
+}
+
+function exact(element: StructuredElement, allowed: readonly string[], required: readonly string[] = []): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
+  if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]}`);
+  const missing = required.filter((name) => element.attributes[name] === undefined);
+  if (missing.length > 0) throw new Error(`${element.name} requires ${missing.join(", ")}`);
+}
+
+function stringAttribute(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${element.name}.${name} must be non-empty text`);
+  }
+  return value.trim();
+}
+
+function referencePath(element: StructuredElement, name: string): string {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof value !== "object" || value.kind !== "reference" || value.path.length === 0) {
+    throw new Error(`${element.name}.${name} must be a whole-value reference`);
+  }
+  return value.path;
+}
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+  return left.module.name === right.module.name
+    && left.module.version === right.module.version
+    && left.name === right.name;
+}
+
+function reference(
+  element: StructuredElement,
+  name: string,
+  expected: SurfaceResolvedReference["type"],
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const path = referencePath(element, name);
+  const result = resolve(path);
+  if (result === undefined) throw new Error(`${element.name}.${name} cannot resolve ${path}`);
+  if (!sameType(result.type, expected)) throw new Error(`${element.name}.${name} has the wrong type`);
+  return result;
+}
+
+function inline<T>(value: SurfaceResolvedReference, subject: string): T {
+  if (value.record?.value.kind !== "inline") throw new Error(`${subject} must reference an authored inline value`);
+  return value.record.value.value as unknown as T;
+}
+
+function bodyText(element: StructuredElement): string {
+  if (element.children.some((child) => child.kind === "element")) {
+    throw new Error(`${element.name} accepts text only`);
+  }
+  const raw = element.children.map((child) => child.kind === "text" ? child.value : "").join("");
+  const lines = raw.replaceAll("\r\n", "\n").split("\n");
+  while (lines[0]?.trim() === "") lines.shift();
+  while (lines.at(-1)?.trim() === "") lines.pop();
+  const indents = lines.filter((line) => line.trim()).map((line) => /^\s*/u.exec(line)?.[0].length ?? 0);
+  const indent = indents.length === 0 ? 0 : Math.min(...indents);
+  return lines.map((line) => line.slice(indent).trimEnd()).join("\n");
+}
+
+function parameterValue(element: StructuredElement): TextScalar {
+  const value = stringAttribute(element, "value");
+  const kind = element.attributes.type ?? "text";
+  if (kind === "text") return value;
+  if (kind === "boolean") {
+    if (value === "true") return true;
+    if (value === "false") return false;
+    throw new Error(`${element.name}.value must be true or false for type boolean`);
+  }
+  if (kind === "number") {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) throw new Error(`${element.name}.value must be a finite number`);
+    return parsed;
+  }
+  throw new Error(`${element.name}.type must be text, number or boolean`);
+}
+
+/** Author one literal graph Text value. */
+export const decodeTextValueSurface: StructuredSurfaceHandler = ({ element }) => {
+  exact(element, ["id"], ["id"]);
+  const id = stringAttribute(element, "id");
+  return {
+    records: [{
+      id,
+      type: textTypes.text,
+      value: { kind: "inline", value: sealText(bodyText(element)) as unknown as CanonicalValue },
+      range: element.range,
+    }],
+    components: [],
+    fragments: [],
+  };
+};
+
+/**
+ * Render one TextTemplate. Param children author scalar bindings; Set/Append
+ * children attach ordinary Text graph edges in source order.
+ */
+export const decodeTextRenderSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, ["id", "template", "recipe"], ["id", "template"]);
+  const id = stringAttribute(element, "id");
+  const template = reference(element, "template", textTypes.template, resolveReference);
+  const initial: Record<string, TextBindingValue> = {};
+  if (element.attributes.recipe !== undefined) {
+    const templateValue = inline<TextTemplate>(template, `${element.name}.template`);
+    verifyTextTemplate(templateValue);
+    const consumed = textTemplateBindingNames(templateValue);
+    const recipe = reference(element, "recipe", svsRecipeType, resolveReference);
+    const value = inline<SvsRecipe>(recipe, `${element.name}.recipe`);
+    for (const [name, item] of Object.entries(value.properties)) {
+      if (!consumed.has(name)) continue;
+      if (typeof item !== "string" && typeof item !== "boolean" && !(typeof item === "number" && Number.isFinite(item))) {
+        throw new Error(`${value.path}.${name} must be text, boolean or a finite number`);
+      }
+      initial[name] = item;
+    }
+  }
+  const explicitParams = new Set<string>();
+  const dynamic: Array<{
+    readonly input: string;
+    readonly name: string;
+    readonly mode: "set" | "append";
+    readonly source: SurfaceResolvedReference;
+  }> = [];
+
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Param, Set or Append children`);
+      continue;
+    }
+    const kind = localName(child.name);
+    if (kind === "Param") {
+      exact(child, ["name", "value", "type"], ["name", "value"]);
+      const name = stringAttribute(child, "name");
+      if (explicitParams.has(name)) throw new Error(`${element.name} repeats Param ${name}`);
+      explicitParams.add(name);
+      initial[name] = parameterValue(child);
+      continue;
+    }
+    if (kind !== "Set" && kind !== "Append") {
+      throw new Error(`${element.name} accepts only Param, Set or Append children`);
+    }
+    exact(child, ["name", "text"], ["name", "text"]);
+    const input = `binding-${String(dynamic.length + 1).padStart(4, "0")}`;
+    dynamic.push({
+      input,
+      name: stringAttribute(child, "name"),
+      mode: kind === "Set" ? "set" : "append",
+      source: reference(child, "text", textTypes.text, resolveReference),
+    });
+  }
+
+  const bindingsId = `${id}.bindings`;
+  const fragment = createTextRenderFragment(dynamic.map((item) => ({ name: item.input })));
+  const records = [{
+    id: bindingsId,
+    type: textTypes.bindings,
+    value: { kind: "inline" as const, value: sealTextBindings(initial) as unknown as CanonicalValue },
+    range: element.range,
+  }, ...dynamic.map((item) => ({
+    id: `${id}.${item.input}`,
+    type: textTypes.binding,
+    value: {
+      kind: "inline" as const,
+      value: sealTextBinding({ name: item.name, mode: item.mode }) as unknown as CanonicalValue,
+    },
+    range: element.range,
+  }))];
+  return {
+    records,
+    components: [{
+      id,
+      fragment: fragment.id,
+      inputs: {
+        template: template.ref,
+        bindings: { kind: "record", id: bindingsId },
+        ...Object.fromEntries(dynamic.flatMap((item) => [[
+          `binding:${item.input}:spec`, { kind: "record" as const, id: `${id}.${item.input}` },
+        ], [
+          `binding:${item.input}:text`, item.source.ref,
+        ]])),
+      },
+      outputs: { text: id },
+      range: element.range,
+    }],
+    fragments: [fragment],
+  };
+};