@sixb/core 0.1.21 → 0.1.22

package/src/artifacts/formula/parser.ts

@@ -0,0 +1,357 @@
+/**
+ * A computed column's formula, as an Excel table writes one: `([@Revenue]-[@Cost])/[@Revenue]`.
+ * `[@Name]` is this row's value in a column, `[Name]` the whole column (only inside an aggregate),
+ * and a name holding brackets or other special characters is bracketed again: `[@[Lead (weeks)]]`.
+ * In a name, `'` escapes the next character, as in Excel.
+ */
+export type FormulaNode =
+  | { readonly kind: "number"; readonly value: number }
+  | { readonly kind: "text"; readonly value: string }
+  | { readonly kind: "boolean"; readonly value: boolean }
+  /** This row's value in a column. */
+  | { readonly kind: "ref"; readonly column: string }
+  /** Every value of a column. */
+  | { readonly kind: "columnRef"; readonly column: string }
+  | { readonly kind: "unary"; readonly op: "-" | "+"; readonly operand: FormulaNode }
+  | {
+      readonly kind: "binary"
+      readonly op: FormulaOperator
+      readonly left: FormulaNode
+      readonly right: FormulaNode
+    }
+  | { readonly kind: "call"; readonly name: string; readonly args: readonly FormulaNode[] }
+
+export type FormulaOperator =
+  | "+"
+  | "-"
+  | "*"
+  | "/"
+  | "^"
+  | "&"
+  | "="
+  | "<>"
+  | "<"
+  | "<="
+  | ">"
+  | ">="
+
+/** A formula that does not parse, with what is wrong where, from the first character as 1. */
+export class FormulaSyntaxError extends Error {
+  constructor(
+    message: string,
+    readonly position: number
+  ) {
+    super(message)
+    this.name = "FormulaSyntaxError"
+  }
+}
+
+type Token =
+  | { readonly kind: "number"; readonly value: number; readonly at: number }
+  | { readonly kind: "text"; readonly value: string; readonly at: number }
+  | { readonly kind: "name"; readonly value: string; readonly at: number }
+  | { readonly kind: "ref"; readonly column: string; readonly row: boolean; readonly at: number }
+  | { readonly kind: "op"; readonly value: string; readonly at: number }
+  | { readonly kind: "end"; readonly at: number }
+
+const OPERATORS = ["<>", "<=", ">=", "+", "-", "*", "/", "^", "&", "=", "<", ">", "(", ")", ","]
+
+function tokens(source: string): Token[] {
+  const list: Token[] = []
+  let index = 0
+  const fail = (message: string, at = index): never => {
+    throw new FormulaSyntaxError(`${message} at character ${at + 1}.`, at + 1)
+  }
+  /** A column's name up to its closing bracket, `'` escaping the next character. */
+  const name = (): string => {
+    let value = ""
+    while (index < source.length && source[index] !== "]") {
+      if (source[index] === "[") fail("A column's name holds '[': escape it as '[")
+      if (source[index] === "'") index += 1
+      value += source[index] ?? ""
+      index += 1
+    }
+    if (source[index] !== "]") fail("A column reference is never closed with ']'")
+    index += 1
+    return value.trim()
+  }
+  while (index < source.length) {
+    const char = source[index] as string
+    const at = index
+    if (/\s/.test(char)) {
+      index += 1
+      continue
+    }
+    if (/[0-9.]/.test(char)) {
+      const match = /^(\d+\.?\d*|\.\d+)(e[-+]?\d+)?/i.exec(source.slice(index))
+      if (!match) fail("A number is not written right")
+      index += (match as RegExpExecArray)[0].length
+      list.push({ kind: "number", value: Number((match as RegExpExecArray)[0]), at })
+      continue
+    }
+    if (char === '"') {
+      let value = ""
+      index += 1
+      for (;;) {
+        if (index >= source.length) fail("A text in quotes is never closed", at)
+        if (source[index] === '"') {
+          if (source[index + 1] === '"') {
+            value += '"'
+            index += 2
+            continue
+          }
+          index += 1
+          break
+        }
+        value += source[index]
+        index += 1
+      }
+      list.push({ kind: "text", value, at })
+      continue
+    }
+    if (char === "[") {
+      index += 1
+      const row = source[index] === "@"
+      if (row) index += 1
+      let column: string
+      if (source[index] === "[") {
+        index += 1
+        column = name()
+        if (source[index] !== "]") fail("A bracketed column name needs its outer ']'")
+        index += 1
+      } else {
+        column = name()
+      }
+      if (!column) fail("A column reference names no column", at)
+      list.push({ kind: "ref", column, row, at })
+      continue
+    }
+    if (/[A-Za-z_]/.test(char)) {
+      const match = /^[A-Za-z_][A-Za-z0-9_.]*/.exec(source.slice(index)) as RegExpExecArray
+      index += match[0].length
+      list.push({ kind: "name", value: match[0].toUpperCase(), at })
+      continue
+    }
+    const operator = OPERATORS.find((candidate) => source.startsWith(candidate, index))
+    if (!operator) fail(`'${char}' is not part of a formula`)
+    index += (operator as string).length
+    list.push({ kind: "op", value: operator as string, at })
+  }
+  list.push({ kind: "end", at: source.length })
+  return list
+}
+
+/** How tightly each operator binds its operands; all bind leftward, `^` too: `2^3^2` is 64. */
+const BINDING: Readonly<Record<string, number>> = {
+  "=": 10,
+  "<>": 10,
+  "<": 10,
+  "<=": 10,
+  ">": 10,
+  ">=": 10,
+  "&": 20,
+  "+": 30,
+  "-": 30,
+  "*": 40,
+  "/": 40,
+  "^": 50,
+}
+/** A sign binds tighter than `^`: `-2^2` is 4, as Excel reads it. */
+const PREFIX = 60
+
+/**
+ * Parses a formula, with or without its leading `=`. Throws a {@link FormulaSyntaxError} that
+ * says what is wrong and where.
+ */
+export function parseFormula(text: string): FormulaNode {
+  const source = text.trim().replace(/^=/, "")
+  const list = tokens(source)
+  let position = 0
+  const peek = () => list[position] as Token
+  const next = () => list[position++] as Token
+  const fail = (message: string, token: Token): never => {
+    throw new FormulaSyntaxError(`${message} at character ${token.at + 1}.`, token.at + 1)
+  }
+  const expect = (value: string) => {
+    const token = next()
+    if (token.kind !== "op" || token.value !== value) {
+      fail(`Expected '${value}'`, token)
+    }
+  }
+
+  const expression = (binding: number): FormulaNode => {
+    let left = operand()
+    for (;;) {
+      const token = peek()
+      if (token.kind !== "op") break
+      const power = BINDING[token.value]
+      if (power === undefined || power <= binding) break
+      next()
+      const right = expression(power)
+      left = { kind: "binary", op: token.value as FormulaOperator, left, right }
+    }
+    return left
+  }
+
+  const operand = (): FormulaNode => {
+    const token = next()
+    switch (token.kind) {
+      case "number":
+        return { kind: "number", value: token.value }
+      case "text":
+        return { kind: "text", value: token.value }
+      case "ref":
+        return token.row
+          ? { kind: "ref", column: token.column }
+          : { kind: "columnRef", column: token.column }
+      case "name": {
+        if (token.value === "TRUE" || token.value === "FALSE") {
+          return { kind: "boolean", value: token.value === "TRUE" }
+        }
+        if (peek().kind !== "op" || (peek() as { value: string }).value !== "(") {
+          return fail(
+            `'${token.value}' is not a function call or a reference; a column is written [@Name]`,
+            token
+          )
+        }
+        next()
+        const args: FormulaNode[] = []
+        if (!(peek().kind === "op" && (peek() as { value: string }).value === ")")) {
+          for (;;) {
+            args.push(expression(0))
+            const separator = peek()
+            if (separator.kind === "op" && separator.value === ",") {
+              next()
+              continue
+            }
+            break
+          }
+        }
+        expect(")")
+        return { kind: "call", name: token.value, args }
+      }
+      case "op":
+        if (token.value === "(") {
+          const inner = expression(0)
+          expect(")")
+          return inner
+        }
+        if (token.value === "-" || token.value === "+") {
+          return { kind: "unary", op: token.value, operand: expression(PREFIX) }
+        }
+        return fail(`'${token.value}' can't start a value`, token)
+      case "end":
+        return fail("The formula ends where a value is expected", token)
+    }
+  }
+
+  const tree = expression(0)
+  const rest = peek()
+  if (rest.kind !== "end") fail("The formula goes on after a complete value", rest)
+  return tree
+}
+
+/** The columns a formula reads, by row or whole. */
+export function formulaDependencies(node: FormulaNode): Set<string> {
+  const columns = new Set<string>()
+  visitReferences(node, (reference) => columns.add(reference.column))
+  return columns
+}
+
+/**
+ * The columns a formula reads in its own row, `[@Revenue]`, apart from those it reads whole,
+ * `[Revenue]` in `SUM([Revenue])`: a value of the second depends on every row's.
+ */
+export function formulaReferences(node: FormulaNode): {
+  readonly row: Set<string>
+  readonly whole: Set<string>
+} {
+  const row = new Set<string>()
+  const whole = new Set<string>()
+  visitReferences(node, (reference) =>
+    (reference.kind === "ref" ? row : whole).add(reference.column)
+  )
+  return { row, whole }
+}
+
+type FormulaReference = Extract<FormulaNode, { readonly kind: "ref" | "columnRef" }>
+
+function visitReferences(node: FormulaNode, found: (reference: FormulaReference) => void): void {
+  const visit = (current: FormulaNode) => {
+    switch (current.kind) {
+      case "ref":
+      case "columnRef":
+        found(current)
+        return
+      case "unary":
+        visit(current.operand)
+        return
+      case "binary":
+        visit(current.left)
+        visit(current.right)
+        return
+      case "call":
+        for (const arg of current.args) visit(arg)
+        return
+      default:
+        return
+    }
+  }
+  visit(node)
+}
+
+/**
+ * A formula with every reference to a column renamed, `[@Revenue]` and `[Revenue]` alike, and
+ * nothing else changed: text in quotes is left as it is, and the new name is bracketed again when
+ * it holds characters a plain reference can't.
+ */
+export function renameColumnReferences(formula: string, from: string, to: string): string {
+  let result = ""
+  let index = 0
+  while (index < formula.length) {
+    const char = formula[index] as string
+    if (char === '"') {
+      // A text in quotes, its quotes doubled, as the parser reads one.
+      let end = index + 1
+      while (end < formula.length) {
+        if (formula[end] === '"' && formula[end + 1] === '"') end += 2
+        else if (formula[end] === '"') break
+        else end += 1
+      }
+      result += formula.slice(index, end + 1)
+      index = end + 1
+      continue
+    }
+    if (char !== "[") {
+      result += char
+      index += 1
+      continue
+    }
+    const start = index
+    index += 1
+    const row = formula[index] === "@"
+    if (row) index += 1
+    const bracketed = formula[index] === "["
+    if (bracketed) index += 1
+    let name = ""
+    while (index < formula.length && formula[index] !== "]") {
+      if (formula[index] === "'") index += 1
+      name += formula[index] ?? ""
+      index += 1
+    }
+    index += bracketed ? 2 : 1
+    result +=
+      name.trim() === from
+        ? columnReference(to, row)
+        : formula.slice(start, Math.min(index, formula.length))
+  }
+  return result
+}
+
+/** A reference to a column: this row's value, or the whole column. */
+function columnReference(name: string, row: boolean): string {
+  const escaped = name.replace(/['[\]#@]/g, "'$&")
+  const plain = /^[A-Za-z0-9_ ]+$/.test(name) && name === name.trim()
+  const inner = plain ? escaped : `[${escaped}]`
+  return row ? `[@${inner}]` : `[${inner}]`
+}

package/src/artifacts/frames/assets.ts

@@ -1,35 +1,50 @@
 import type { ArtifactFrameTarget } from "../../storage/artifacts/types"
 import { isArtifactAddress, parseArtifactAddress } from "../address"
 import { decodeHtmlEntities } from "../html"
-import { FRAME_ASSET_PREFIX } from "../publish/validate/slides"
-import { FRAME_KIT_CSS } from "./kit"
+import { FRAME_ASSET_PREFIX } from "../publish/validate/html"
+import type { FrameLayout } from "./entries"
+import { FRAME_DECK_CSS, FRAME_PAGE_CSS } from "./kit"
 import { frameRuntime } from "./runtime"
 
 /**
- * The files a frame gets besides the version's own, under `__sixb/`, which a version may not use.
- * The server serves them to the app's frames, and the Agent's layout check serves them to its
- * browser, so both lay a deck out the same way.
+ * The files a frame gets besides the version's own, under `__sixb/`, which a version may not use:
+ * a kit per layout, and the runtime. The server serves them to the app's frames, and the Agent's
+ * layout check serves them to its browser, so both lay a version out the same way.
  */
 export const FRAME_ASSETS: Readonly<
   Record<string, { readonly body: string; readonly type: string }>
 > = {
-  [`${FRAME_ASSET_PREFIX}kit.css`]: { body: FRAME_KIT_CSS, type: "text/css; charset=utf-8" },
+  [`${FRAME_ASSET_PREFIX}deck.css`]: { body: FRAME_DECK_CSS, type: "text/css; charset=utf-8" },
+  [`${FRAME_ASSET_PREFIX}page.css`]: { body: FRAME_PAGE_CSS, type: "text/css; charset=utf-8" },
   [`${FRAME_ASSET_PREFIX}runtime.js`]: {
     body: `(${frameRuntime.toString()})()\n`,
     type: "text/javascript; charset=utf-8",
   },
 }
 
-const INJECTED = `<link rel="stylesheet" href="${FRAME_ASSET_PREFIX}kit.css"><script src="${FRAME_ASSET_PREFIX}runtime.js"></script>`
+/** The kit for the layout and the runtime, which reads the layout from its own tag. */
+function injected(layout: FrameLayout, base: string): string {
+  return `<link rel="stylesheet" href="${base}${FRAME_ASSET_PREFIX}${layout}.css"><script src="${base}${FRAME_ASSET_PREFIX}runtime.js" data-sixb-layout="${layout}"></script>`
+}
+
+/**
+ * The way from an entry back to its frame's root, where `__sixb/` is: none for `index.html`,
+ * `../` for a canvas's `boards/home.html`.
+ */
+function rootOf(entry: string): string {
+  return "../".repeat(entry.split("/").length - 1)
+}
 
 /**
- * A deck's entry with the kit and the runtime first in its `<head>`, before anything of its own,
- * so the deck's styles and scripts build on them. Exactly once, whatever the markup: in `<head>`
+ * An entry with its layout's kit and the runtime first in its `<head>`, before anything of its
+ * own, so its styles and scripts build on them. Exactly once, whatever the markup: in `<head>`
  * when the page has one, else first in `<html>`, else right after the doctype, so a page without
  * either still renders in standards mode. Each element is looked for by parsing, not by matching
- * text, so a `<head>` inside a comment or a script's string is not one.
+ * text, so a `<head>` inside a comment or a script's string is not one. `entry` is where the page
+ * is in the version, so an entry in a folder, as a canvas's boards are, finds them.
  */
-export function injectFrameAssets(html: string): string {
+export function injectFrameAssets(html: string, layout: FrameLayout, entry = "index.html"): string {
+  const assets = injected(layout, rootOf(entry))
   for (const selector of ["head", "html"]) {
     let injected = false
     const rewritten = new HTMLRewriter()
@@ -37,36 +52,37 @@ export function injectFrameAssets(html: string): string {
         element(element) {
           if (injected) return
           injected = true
-          element.prepend(INJECTED, { html: true })
+          element.prepend(assets, { html: true })
         },
       })
       .transform(html)
     if (injected) return rewritten
   }
   const doctype = /^\s*<!doctype[^>]*>/i.exec(html)?.[0] ?? ""
-  return `${doctype}${INJECTED}${html.slice(doctype.length)}`
+  return `${doctype}${assets}${html.slice(doctype.length)}`
 }
 
 /** Where a frame serves a file another artifact lends it: `__sixb/ref/<id>@<version>/<path>`. */
 export const FRAME_REFERENCE_PREFIX = `${FRAME_ASSET_PREFIX}ref/`
 
-/** The path, under a frame's base, of a file one of its targets lends it. */
-function frameReferencePath(target: ArtifactFrameTarget): string | null {
+/** The path, from an entry, of a file one of its frame's targets lends it. */
+function frameReferencePath(target: ArtifactFrameTarget, entry: string): string | null {
   const file = parseArtifactAddress(target.address)?.path
   if (!file) return null
   const path = file.split("/").map(encodeURIComponent).join("/")
-  return `${FRAME_REFERENCE_PREFIX}${target.artifactId}@${target.version}/${path}`
+  return `${rootOf(entry)}${FRAME_REFERENCE_PREFIX}${target.artifactId}@${target.version}/${path}`
 }
 
 /**
- * Points each image a deck shows from another artifact (`<img src="artifact:…">`) at the copy its
+ * Points each image an entry shows from another artifact (`<img src="artifact:…">`) at the copy its
  * frame serves, marked `data-sixb-ref`. An image its reader cannot see, or that the frame has
  * no target for, loses its source and is marked unavailable: the kit draws it as an empty box.
  * Addresses are compared as publishing recorded them, with their entities decoded.
  */
 export function rewriteFrameReferences(
   html: string,
-  targets: readonly ArtifactFrameTarget[]
+  targets: readonly ArtifactFrameTarget[],
+  entry = "index.html"
 ): string {
   return new HTMLRewriter()
     .on("img[src]", {
@@ -74,7 +90,7 @@ export function rewriteFrameReferences(
         const source = decodeHtmlEntities(element.getAttribute("src") ?? "").trim()
         if (!isArtifactAddress(source)) return
         const target = targets.find((candidate) => candidate.address === source)
-        const path = target ? frameReferencePath(target) : null
+        const path = target ? frameReferencePath(target, entry) : null
         if (path) {
           element.setAttribute("src", path)
           element.setAttribute("data-sixb-ref", "")

package/src/artifacts/frames/entries.ts

@@ -0,0 +1,35 @@
+import type { ArtifactKind } from "../kinds"
+import type { ArtifactOutline } from "../outline"
+
+/**
+ * How the frame's runtime lays out what it serves: a deck shows 1280×720 slides scaled to fit, one
+ * at a time or all at once; a page scrolls like any web page, as a canvas's boards do.
+ */
+export type FrameLayout = "deck" | "page"
+
+/** The kinds that open in a sandboxed frame, each in its layout. */
+const FRAME_LAYOUTS: Partial<Readonly<Record<ArtifactKind, FrameLayout>>> = {
+  slides: "deck",
+  page: "page",
+  canvas: "page",
+}
+
+/** A kind's frame layout, or null for a kind Sixb draws natively. */
+export function frameLayout(kind: ArtifactKind): FrameLayout | null {
+  return FRAME_LAYOUTS[kind] ?? null
+}
+
+/**
+ * The files of a version its frame serves as pages, with the kit and the runtime first in their
+ * `<head>`: a deck's or a page's entry, or each of a canvas's boards; none for a kind that does
+ * not open in a frame.
+ */
+export function frameEntries(version: {
+  readonly entry: string
+  readonly outline: ArtifactOutline
+}): readonly string[] {
+  if (version.outline.kind === "canvas") {
+    return version.outline.items.flatMap((item) => (item.type === "board" ? [item.file] : []))
+  }
+  return frameLayout(version.outline.kind) ? [version.entry] : []
+}

package/src/artifacts/frames/grants.ts

@@ -6,6 +6,7 @@ import type {
 } from "../../storage/artifacts/types"
 import { parseArtifactAddress } from "../address"
 import { ArtifactRequestError } from "../errors"
+import { frameLayout } from "./entries"
 
 /** Path prefix of the route that serves a version's files to its frame. */
 export const ARTIFACT_FRAME_ROUTE_PREFIX = "/api/artifact-frames/"
@@ -27,10 +28,10 @@ type ReadArtifactVersion = (
 ) => Promise<ArtifactVersionRecord | null>
 
 /**
- * Issues a link that serves a deck's version to a sandboxed frame, with the files it embeds from
- * other artifacts that `read` finds. The token in the link is the credential: only its hash is
- * stored. Whoever asks must already have been allowed to read the version, and `read` reads as
- * them. Only a deck opens in a frame, since the frame serves its entry as a page.
+ * Issues a link that serves a version to a sandboxed frame, with the files it embeds from other
+ * artifacts that `read` finds. The token in the link is the credential: only its hash is stored.
+ * Whoever asks must already have been allowed to read the version, and `read` reads as them. Only
+ * a kind with a frame layout opens in one, since the frame serves its entry as a page.
  */
 export async function createArtifactFrame(input: {
   readonly projectId: string
@@ -40,10 +41,10 @@ export async function createArtifactFrame(input: {
   readonly now?: Date
 }): Promise<ArtifactFrame> {
   const { version } = input
-  if (version.outline.kind !== "slides") {
+  if (!frameLayout(version.outline.kind)) {
     throw new ArtifactRequestError(
       "artifact_kind_mismatch",
-      `[Sixb] Only a deck opens in a frame; '${version.artifactId}' is a ${version.outline.kind}. Read its files instead.`
+      `[Sixb] '${version.artifactId}' is a ${version.outline.kind}, which does not open in a frame. Read its files instead.`
     )
   }
   const createdAt = input.now ?? new Date()
@@ -93,8 +94,8 @@ async function frameTargets(
 }
 
 /**
- * What a frame link serves: its deck's version, and what it may show from other artifacts; `null`
- * once the link is unknown, expired, or its version gone, and for a version that is not a deck.
+ * What a frame link serves: its version, and what it may show from other artifacts; `null` once
+ * the link is unknown, expired, or its version gone, and for a kind that does not open in a frame.
  */
 export async function resolveArtifactFrame(input: {
   readonly projectId: string
@@ -116,7 +117,7 @@ export async function resolveArtifactFrame(input: {
     artifactId: grant.artifactId,
     version: grant.version,
   })
-  return version?.outline.kind === "slides" ? { version, targets: grant.targets } : null
+  return version && frameLayout(version.outline.kind) ? { version, targets: grant.targets } : null
 }
 
 function hashToken(token: string): string {

package/src/artifacts/frames/index.ts

@@ -1,15 +1,21 @@
 /**
  * Frames for this repo's packages: the server issues and serves them, with the kit and runtime,
- * and the Agent's layout check lays a deck out in them.
+ * and the Agent's layout check lays a version out in them.
  */
 
-export { SLIDES_ENTRY } from "../publish/validate/slides"
+export { HTML_ENTRY } from "../publish/validate/html"
+// What a frame's `sixb.query` reads: the route serves it, and the layout check serves it too.
+export {
+  type SerializedArtifactQueryResult,
+  serializeArtifactQueryResult,
+} from "../serialize-query"
 export {
   FRAME_ASSETS,
   FRAME_REFERENCE_PREFIX,
   injectFrameAssets,
   rewriteFrameReferences,
 } from "./assets"
+export { type FrameLayout, frameEntries, frameLayout } from "./entries"
 export { ARTIFACT_FRAME_ROUTE_PREFIX, createArtifactFrame, resolveArtifactFrame } from "./grants"
 export { FRAME_DEFAULT_THEMES } from "./kit"
 export { type LayoutProblem, layoutProbe } from "./probe"