@sixb/core 0.1.20 → 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

@@ -0,0 +1,104 @@
+import type { ArtifactFrameTarget } from "../../storage/artifacts/types"
+import { isArtifactAddress, parseArtifactAddress } from "../address"
+import { decodeHtmlEntities } from "../html"
+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:
+ * 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}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",
+  },
+}
+
+/** 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)
+}
+
+/**
+ * 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. `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, 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()
+      .on(selector, {
+        element(element) {
+          if (injected) return
+          injected = true
+          element.prepend(assets, { html: true })
+        },
+      })
+      .transform(html)
+    if (injected) return rewritten
+  }
+  const doctype = /^\s*<!doctype[^>]*>/i.exec(html)?.[0] ?? ""
+  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, 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 `${rootOf(entry)}${FRAME_REFERENCE_PREFIX}${target.artifactId}@${target.version}/${path}`
+}
+
+/**
+ * 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[],
+  entry = "index.html"
+): string {
+  return new HTMLRewriter()
+    .on("img[src]", {
+      element(element) {
+        const source = decodeHtmlEntities(element.getAttribute("src") ?? "").trim()
+        if (!isArtifactAddress(source)) return
+        const target = targets.find((candidate) => candidate.address === source)
+        const path = target ? frameReferencePath(target, entry) : null
+        if (path) {
+          element.setAttribute("src", path)
+          element.setAttribute("data-sixb-ref", "")
+        } else {
+          element.removeAttribute("src")
+          element.setAttribute("data-sixb-ref", "unavailable")
+        }
+      },
+    })
+    .transform(html)
+}

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

@@ -0,0 +1,125 @@
+import { createHash, randomBytes } from "node:crypto"
+import type {
+  ArtifactFrameTarget,
+  ArtifactStorage,
+  ArtifactVersionRecord,
+} 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/"
+
+/** A frame link lasts an hour; the app asks for a new one before it runs out. */
+const FRAME_LIFETIME_MS = 60 * 60 * 1000
+/** 32 random bytes in base64url. */
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/
+
+export interface ArtifactFrame {
+  /** The frame's base, ending in `/`: the version's files are served under it by their paths. */
+  readonly path: string
+  readonly expiresAt: Date
+}
+
+type ReadArtifactVersion = (
+  artifactId: string,
+  version: number | "latest"
+) => Promise<ArtifactVersionRecord | null>
+
+/**
+ * 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
+  readonly storage: ArtifactStorage
+  readonly version: ArtifactVersionRecord
+  readonly read?: ReadArtifactVersion
+  readonly now?: Date
+}): Promise<ArtifactFrame> {
+  const { version } = input
+  if (!frameLayout(version.outline.kind)) {
+    throw new ArtifactRequestError(
+      "artifact_kind_mismatch",
+      `[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()
+  const expiresAt = new Date(createdAt.getTime() + FRAME_LIFETIME_MS)
+  const token = randomBytes(32).toString("base64url")
+  await input.storage.createFrameGrant({
+    projectId: input.projectId,
+    tokenHash: hashToken(token),
+    artifactId: version.artifactId,
+    version: version.version,
+    targets: input.read ? await frameTargets(version, input.read) : [],
+    createdAt,
+    expiresAt,
+  })
+  return { path: `${ARTIFACT_FRAME_ROUTE_PREFIX}${token}/`, expiresAt }
+}
+
+/**
+ * The files from other artifacts a version's frame may show its reader: each file it embeds
+ * (`<img src="artifact:…/figure.svg">`) that `read`, as the reader, finds, at the version the
+ * address pins or the latest. A chart, range, or section is drawn by the app over the frame, under
+ * the reader's own session, and needs nothing here.
+ */
+async function frameTargets(
+  version: ArtifactVersionRecord,
+  read: ReadArtifactVersion
+): Promise<ArtifactFrameTarget[]> {
+  const targets: ArtifactFrameTarget[] = []
+  for (const reference of version.references) {
+    if (
+      reference.as !== "embed" ||
+      targets.some((target) => target.address === reference.address)
+    ) {
+      continue
+    }
+    const address = parseArtifactAddress(reference.address)
+    if (!address?.path) continue
+    const target = await read(address.artifactId, address.version ?? "latest").catch(() => null)
+    if (!target?.files.some((file) => file.path === address.path)) continue
+    targets.push({
+      address: reference.address,
+      artifactId: target.artifactId,
+      version: target.version,
+    })
+  }
+  return targets
+}
+
+/**
+ * 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
+  readonly storage: ArtifactStorage
+  readonly token: string
+  readonly now?: Date
+}): Promise<{
+  readonly version: ArtifactVersionRecord
+  readonly targets: readonly ArtifactFrameTarget[]
+} | null> {
+  if (!TOKEN_PATTERN.test(input.token)) return null
+  const grant = await input.storage.findFrameGrant({
+    projectId: input.projectId,
+    tokenHash: hashToken(input.token),
+  })
+  if (!grant || grant.expiresAt <= (input.now ?? new Date())) return null
+  const version = await input.storage.getVersion({
+    projectId: input.projectId,
+    artifactId: grant.artifactId,
+    version: grant.version,
+  })
+  return version && frameLayout(version.outline.kind) ? { version, targets: grant.targets } : null
+}
+
+function hashToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex")
+}

package/src/artifacts/frames/index.ts

@@ -0,0 +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 version out in them.
+ */
+
+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"