@sixb/core 0.1.20 → 0.1.22

package/src/artifacts/publish/references.ts

@@ -0,0 +1,135 @@
+import { type Principal, principalsEqual } from "../../auth"
+import type {
+  ArtifactRecord,
+  ArtifactStorage,
+  ArtifactVersionRecord,
+} from "../../storage/artifacts/types"
+import { parseArtifactAddress } from "../address"
+import { ARTIFACT_LIMITS } from "../limits"
+import type { ArtifactReference } from "../references"
+import { resolveArtifactAddress } from "../resolve"
+import type { ArtifactWarning } from "../warnings"
+import { invalidArtifact } from "./files"
+
+/** An address a validator found in a version, before it is resolved. */
+export type FoundReference = Omit<ArtifactReference, "resolvedVersion">
+
+interface ReferenceContext {
+  readonly projectId: string
+  readonly storage: ArtifactStorage
+  /** Whether an address may name this artifact: one whoever publishes can read. */
+  readonly readable: (artifact: ArtifactRecord) => Promise<boolean>
+  /** The artifact being published, which an address may not name. */
+  readonly artifactId?: string
+}
+
+/**
+ * Resolves every address a version uses against what its author can read, recording the version
+ * each one resolved to. An address that resolves to nothing refuses the version, saying where it
+ * is and what the target has instead.
+ */
+export async function resolveReferences(
+  context: ReferenceContext,
+  found: readonly FoundReference[]
+): Promise<ArtifactReference[]> {
+  if (found.length > ARTIFACT_LIMITS.maxReferences) {
+    throw invalidArtifact(
+      `A version may refer to at most ${ARTIFACT_LIMITS.maxReferences} artifacts; this one has ${found.length} addresses.`
+    )
+  }
+  const artifacts = new Map<string, Promise<ArtifactRecord | null>>()
+  const versions = new Map<string, Promise<ArtifactVersionRecord | null>>()
+  const resolved: ArtifactReference[] = []
+  for (const reference of found) {
+    const where = reference.at
+      ? `In '${reference.at}', '${reference.address}'`
+      : `'${reference.address}'`
+    const address = parseArtifactAddress(reference.address)
+    if (!address) {
+      throw invalidArtifact(
+        `${where} is not an artifact address: write artifact:<id>[@<version>][/<file>][#<part>], such as artifact:art_k3m9q2x7tp#chart=revenue.`
+      )
+    }
+    if (address.artifactId === context.artifactId) {
+      throw invalidArtifact(
+        `${where} names the artifact being published. Link to one of its sections with #<slug> instead.`
+      )
+    }
+    let artifact = artifacts.get(address.artifactId)
+    if (!artifact) {
+      artifact = context.storage
+        .get({ projectId: context.projectId, id: address.artifactId })
+        .then(async (record) => (record && (await context.readable(record)) ? record : null))
+      artifacts.set(address.artifactId, artifact)
+    }
+    const record = await artifact
+    if (!record) {
+      throw invalidArtifact(`${where} names no artifact you can read.`)
+    }
+    const number = address.version ?? record.latestVersion
+    const key = `${record.id}@${number}`
+    let version = versions.get(key)
+    if (!version) {
+      version = context.storage.getVersion({
+        projectId: context.projectId,
+        artifactId: record.id,
+        version: number,
+      })
+      versions.set(key, version)
+    }
+    const target = await version
+    if (!target) throw invalidArtifact(`${where}: “${record.title}” has no version ${number}.`)
+    const result = resolveArtifactAddress(address, { kind: record.kind, ...target })
+    if ("problem" in result) {
+      throw invalidArtifact(`${where}: “${target.title}” ${result.problem}.`)
+    }
+    resolved.push({ ...reference, resolvedVersion: target.version })
+  }
+  return resolved
+}
+
+/**
+ * The artifacts a new version breaks: each one whose latest version follows this artifact's latest
+ * and names something this version no longer has. Only artifacts the author can read are named,
+ * and only those the version breaks are checked: most dependents cost no read.
+ */
+export async function brokenDependents(
+  context: ReferenceContext,
+  artifact: ArtifactRecord,
+  version: ArtifactVersionRecord
+): Promise<ArtifactWarning[]> {
+  const dependents = await context.storage.listReferencingVersions({
+    projectId: context.projectId,
+    artifactId: artifact.id,
+  })
+  const warnings: ArtifactWarning[] = []
+  for (const dependent of dependents) {
+    if (dependent.artifactId === artifact.id) continue
+
+    const broken: ArtifactWarning[] = []
+    for (const reference of dependent.references) {
+      const address = parseArtifactAddress(reference.address)
+      // A pinned address keeps showing the version it names.
+      if (address?.artifactId !== artifact.id || address.version !== undefined) continue
+      const result = resolveArtifactAddress(address, { kind: artifact.kind, ...version })
+      if (!("problem" in result)) continue
+      broken.push({
+        code: "reference_broken",
+        message: `“${dependent.title}” (${dependent.artifactId}) ${reference.as === "embed" ? "shows" : "links to"} ${reference.address}, but version ${version.version} ${result.problem}. Publish its next version with an address that resolves, or restore what it names.`,
+      })
+    }
+    if (broken.length === 0) continue
+
+    const owner = await context.storage.get({
+      projectId: context.projectId,
+      id: dependent.artifactId,
+    })
+    if (owner && (await context.readable(owner))) warnings.push(...broken)
+  }
+  return warnings
+}
+
+/** What its author reads when nothing else is said: their own artifacts, or all for system code. */
+export function ownArtifacts(author: Principal): (artifact: ArtifactRecord) => Promise<boolean> {
+  return async (artifact) => author.type === "system" || principalsEqual(author, artifact.owner)
+}

package/src/artifacts/publish/validate/canvas.ts

@@ -0,0 +1,118 @@
+import { posix } from "node:path"
+import type { ArtifactFile } from "../../../storage/artifacts/types"
+import { CANVAS_FILE, type Canvas, parseCanvas } from "../../canvas"
+import { ARTIFACT_LIMITS } from "../../limits"
+import type { CanvasOutline, CanvasOutlineItem } from "../../outline"
+import type { ArtifactWarning } from "../../warnings"
+import { type ArtifactBlobStorage, invalidArtifact, readArtifactText } from "../files"
+import type { FoundReference } from "../references"
+import { readHtmlReferences, refuseFrameAssetPaths } from "./html"
+
+/**
+ * Reads a canvas: `canvas.json`, then each board's HTML, which must be one of the version's files.
+ * The addresses its embeds show and its boards use are returned to resolve, each at its item's id.
+ * Boards that overlap, and notes or text drawn over a board, are warnings: the reader sees a page
+ * covered.
+ */
+export async function validateCanvas(
+  blobStorage: ArtifactBlobStorage,
+  files: readonly ArtifactFile[]
+): Promise<{
+  readonly entry: string
+  readonly outline: CanvasOutline
+  readonly references: readonly FoundReference[]
+  readonly warnings: readonly ArtifactWarning[]
+}> {
+  const byPath = new Map(files.map((file) => [file.path, file]))
+  const canvasFile = byPath.get(CANVAS_FILE)
+  if (!canvasFile) {
+    throw invalidArtifact(
+      `A canvas is '${CANVAS_FILE}', listing its items, with the HTML files its boards show beside it.`
+    )
+  }
+  refuseFrameAssetPaths(files, "the canvas")
+  const parsed = parseCanvas(
+    await readArtifactText(blobStorage, canvasFile, ARTIFACT_LIMITS.maxCanvasBytes)
+  )
+  if ("error" in parsed) throw invalidArtifact(parsed.error)
+  const { canvas } = parsed
+
+  const references: FoundReference[] = []
+  for (const item of canvas.items) {
+    if (item.type === "embed") references.push({ address: item.src, as: "embed", at: item.id })
+    if (item.type !== "board") continue
+    const file = byPath.get(posix.normalize(item.file))
+    if (!file) {
+      throw invalidArtifact(
+        `${CANVAS_FILE} board '${item.id}' shows '${item.file}', which is not one of the canvas's files.`
+      )
+    }
+    const rewriter = new HTMLRewriter()
+    const { references: found, refusal } = readHtmlReferences(rewriter, () => item.id, item.file)
+    rewriter.transform(await readArtifactText(blobStorage, file, ARTIFACT_LIMITS.maxBoardBytes))
+    const refused = refusal()
+    if (refused) throw invalidArtifact(`Board '${item.id}': ${refused}`)
+    references.push(...found)
+  }
+
+  return {
+    entry: CANVAS_FILE,
+    outline: {
+      kind: "canvas",
+      items: canvas.items.flatMap((item): CanvasOutlineItem[] => {
+        const title = item.type === "board" || item.type === "section" ? item.title : undefined
+        const named = { id: item.id, ...(title ? { title } : {}) }
+        if (item.type === "board") {
+          return [
+            { ...named, type: "board", file: posix.normalize(item.file), w: item.w, h: item.h },
+          ]
+        }
+        return item.type === "section" ? [{ ...named, type: "section" }] : []
+      }),
+    },
+    references,
+    warnings: layoutWarnings(canvas),
+  }
+}
+
+interface Box {
+  readonly x: number
+  readonly y: number
+  readonly w: number
+  readonly h: number
+}
+
+const overlaps = (a: Box, b: Box) =>
+  a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h
+
+/**
+ * What covers a board on the canvas: another board over it, or a note or a text whose top left
+ * corner lands on it. A note's height follows its text, so only its corner is sure; a section
+ * holds boards on purpose.
+ */
+function layoutWarnings(canvas: Canvas): ArtifactWarning[] {
+  const boards = canvas.items.flatMap((item) => (item.type === "board" ? [item] : []))
+  const warnings: ArtifactWarning[] = []
+  boards.forEach((board, index) => {
+    for (const other of boards.slice(index + 1)) {
+      if (!overlaps(board, other)) continue
+      warnings.push({
+        code: "canvas_overlap",
+        part: board.id,
+        message: `Boards '${board.id}' and '${other.id}' overlap, so one covers the other's page: leave 80 pixels between boards in a row and 160 between rows.`,
+      })
+    }
+  })
+  for (const item of canvas.items) {
+    if (item.type !== "note" && item.type !== "text") continue
+    const corner = { x: item.x, y: item.y, w: 1, h: 1 }
+    const board = boards.find((candidate) => overlaps(candidate, corner))
+    if (!board) continue
+    warnings.push({
+      code: "canvas_covers_board",
+      part: item.id,
+      message: `${item.type === "note" ? "Note" : "Text"} '${item.id}' sits on board '${board.id}' and covers its page: put it beside the board, and an arrow to it when it is about the board.`,
+    })
+  }
+  return warnings
+}

package/src/artifacts/publish/validate/document.ts

@@ -0,0 +1,114 @@
+import { posix } from "node:path"
+import type { ArtifactFile } from "../../../storage/artifacts/types"
+import { isArtifactAddress } from "../../address"
+import { decodeHtmlEntities } from "../../html"
+import { ARTIFACT_LIMITS } from "../../limits"
+import { createHeadingSlugger, type DocumentHeading, type DocumentOutline } from "../../outline"
+import { type ArtifactBlobStorage, invalidArtifact, readArtifactText } from "../files"
+import type { FoundReference } from "../references"
+
+/** The file a document renders from. */
+export const DOCUMENT_ENTRY = "document.md"
+
+/**
+ * Reads a document's Markdown: its headings become the outline, and every image must be a file in
+ * the version or an `artifact:` address, so the document renders the same wherever it is opened.
+ * The addresses it shows and links to are returned with the section each sits in, to resolve.
+ */
+export async function validateDocument(
+  blobStorage: ArtifactBlobStorage,
+  files: readonly ArtifactFile[]
+): Promise<{
+  readonly entry: string
+  readonly outline: DocumentOutline
+  readonly references: readonly FoundReference[]
+}> {
+  const entry = files.find((file) => file.path === DOCUMENT_ENTRY)
+  if (!entry) throw invalidArtifact(`A document needs its Markdown in '${DOCUMENT_ENTRY}'.`)
+  const markdown = await readArtifactText(blobStorage, entry, ARTIFACT_LIMITS.maxDocumentBytes)
+
+  // The same options the docs site renders with, so headings and images read the same way.
+  const html = Bun.markdown.html(markdown, {
+    tables: true,
+    strikethrough: true,
+    tasklists: true,
+    autolinks: true,
+  })
+  const headings: { depth: number; text: string }[] = []
+  const images: string[] = []
+  // Each address with the index of the heading it follows, -1 before the first.
+  const addresses: { address: string; as: "embed" | "link"; heading: number }[] = []
+  let heading: { depth: number; text: string } | null = null
+  new HTMLRewriter()
+    .on("h1, h2, h3, h4, h5, h6", {
+      element(element) {
+        heading = { depth: Number(element.tagName.slice(1)), text: "" }
+        headings.push(heading)
+        element.onEndTag(() => {
+          heading = null
+        })
+      },
+      text(chunk) {
+        if (heading) heading.text += chunk.text
+      },
+    })
+    .on("img", {
+      element(element) {
+        const source = decodeHtmlEntities(element.getAttribute("src") ?? "")
+        if (isArtifactAddress(source)) {
+          addresses.push({ address: source.trim(), as: "embed", heading: headings.length - 1 })
+        } else {
+          images.push(source)
+        }
+      },
+    })
+    .on("a", {
+      element(element) {
+        const href = decodeHtmlEntities(element.getAttribute("href") ?? "")
+        if (isArtifactAddress(href)) {
+          addresses.push({ address: href.trim(), as: "link", heading: headings.length - 1 })
+        }
+      },
+    })
+    .transform(html)
+
+  const paths = new Set(files.map((file) => file.path))
+  for (const source of images) checkImage(source, paths)
+
+  const slug = createHeadingSlugger()
+  const outlined = headings.map(({ depth, text }): DocumentHeading => {
+    const plain = decodeHtmlEntities(text).replace(/\s+/g, " ").trim()
+    return { depth, text: plain, slug: slug(plain) }
+  })
+  return {
+    entry: DOCUMENT_ENTRY,
+    outline: { kind: "document", headings: outlined },
+    references: addresses.map(({ address, as, heading: index }) => ({
+      address,
+      as,
+      at: outlined[index]?.slug ?? "",
+    })),
+  }
+}
+
+function checkImage(source: string, paths: ReadonlySet<string>): void {
+  if (source === "" || source.startsWith("//") || /^[a-z][a-z\d+.-]*:/i.test(source)) {
+    throw invalidArtifact(
+      `${DOCUMENT_ENTRY} shows the image '${source}'. Images must be files in the artifact, by their relative path, or another artifact's address, such as artifact:art_k3m9q2x7tp#chart=revenue.`
+    )
+  }
+  const path = posix.normalize(safeDecodeUri(source.split(/[?#]/)[0] ?? ""))
+  if (!paths.has(path)) {
+    throw invalidArtifact(
+      `${DOCUMENT_ENTRY} shows the image '${source}', which is not one of the artifact's files.`
+    )
+  }
+}
+
+function safeDecodeUri(value: string): string {
+  try {
+    return decodeURI(value)
+  } catch {
+    return value
+  }
+}

package/src/artifacts/publish/validate/file.ts

@@ -0,0 +1,19 @@
+import { inferFileMediaType } from "../../../blob-storage/media-type"
+import type { ArtifactFile } from "../../../storage/artifacts/types"
+import type { FileOutline } from "../../outline"
+import { invalidArtifact } from "../files"
+
+/** A file artifact is one file of any type, delivered as it is. */
+export function validateFileArtifact(files: readonly ArtifactFile[]): {
+  readonly entry: string
+  readonly outline: FileOutline
+} {
+  const [file] = files
+  if (!file || files.length > 1) {
+    throw invalidArtifact(`A file artifact holds exactly one file; this one has ${files.length}.`)
+  }
+  return {
+    entry: file.path,
+    outline: { kind: "file", mediaType: file.file.mediaType ?? inferFileMediaType(file.path) },
+  }
+}

package/src/artifacts/publish/validate/html.ts

@@ -0,0 +1,78 @@
+import type { ArtifactFile } from "../../../storage/artifacts/types"
+import { isArtifactAddress, parseArtifactAddress } from "../../address"
+import { decodeHtmlEntities } from "../../html"
+import { invalidArtifact } from "../files"
+import type { FoundReference } from "../references"
+
+/** The file a web artifact, a deck or a page, renders from. */
+export const HTML_ENTRY = "index.html"
+
+/** Where the frame serves the kit and the runtime, beside a web artifact's own files. */
+export const FRAME_ASSET_PREFIX = "__sixb/"
+
+/** Refuses a file under `__sixb/`, where the frame serves its own: it would never be served. */
+export function refuseFrameAssetPaths(files: readonly ArtifactFile[], what: string): void {
+  const reserved = files.find((file) => file.path.startsWith(FRAME_ASSET_PREFIX))
+  if (reserved) {
+    throw invalidArtifact(
+      `'${reserved.path}' is under ${FRAME_ASSET_PREFIX}, where Sixb serves ${what}'s kit and runtime: move it.`
+    )
+  }
+}
+
+/**
+ * Reads the `artifact:` addresses a web artifact's HTML uses, to resolve: links (`<a href>`),
+ * files it shows from other artifacts (`<img src>`), and anything else it shows (`<sixb-embed
+ * src>`), a chart, a range, a section, or a slide, which the app draws over the frame. `at` names
+ * where each sits, such as a deck's slide, and `file` the HTML file it reads. The first thing that
+ * would not render is the refusal.
+ */
+export function readHtmlReferences(
+  rewriter: HTMLRewriter,
+  at: () => string,
+  file: string = HTML_ENTRY
+): { readonly references: FoundReference[]; readonly refusal: () => string | undefined } {
+  const references: FoundReference[] = []
+  let refused: string | undefined
+  rewriter
+    .on("a[href]", {
+      element(element) {
+        const href = decodeHtmlEntities(element.getAttribute("href") ?? "")
+        if (isArtifactAddress(href)) {
+          references.push({ address: href.trim(), as: "link", at: at() })
+        }
+      },
+    })
+    .on("img[src]", {
+      element(element) {
+        const source = decodeHtmlEntities(element.getAttribute("src") ?? "").trim()
+        if (!isArtifactAddress(source)) return
+        if (!parseArtifactAddress(source)?.path) {
+          refused ??= `An <img> shows a file from another artifact, and '${source}' names none: show a chart, a range, a section, or a slide with <sixb-embed src="${source}"></sixb-embed>.`
+          return
+        }
+        references.push({ address: source, as: "embed", at: at() })
+      },
+    })
+    .on("sixb-embed", {
+      element(element) {
+        const source = decodeHtmlEntities(element.getAttribute("src") ?? "").trim()
+        if (!isArtifactAddress(source)) {
+          refused ??= `<sixb-embed> shows another artifact: give it src="artifact:…", such as artifact:art_k3m9q2x7tp#chart=revenue.`
+          return
+        }
+        references.push({ address: source, as: "embed", at: at() })
+      },
+    })
+    .on("iframe[src], object[data], embed[src]", {
+      element(element) {
+        const source = decodeHtmlEntities(
+          element.getAttribute("src") ?? element.getAttribute("data") ?? ""
+        ).trim()
+        if (isArtifactAddress(source)) {
+          refused ??= `${file} frames '${source}': show another artifact with <sixb-embed src="${source}"></sixb-embed>, or a file of one with <img>.`
+        }
+      },
+    })
+  return { references, refusal: () => refused }
+}

package/src/artifacts/publish/validate/page.ts

@@ -0,0 +1,65 @@
+import type { ArtifactFile } from "../../../storage/artifacts/types"
+import { decodeHtmlEntities } from "../../html"
+import { ARTIFACT_LIMITS } from "../../limits"
+import type { PageOutline } from "../../outline"
+import { type ArtifactBlobStorage, invalidArtifact, readArtifactText } from "../files"
+import type { FoundReference } from "../references"
+import { HTML_ENTRY, readHtmlReferences, refuseFrameAssetPaths } from "./html"
+
+/**
+ * Reads a page: `index.html` and the files it loads beside it, its scripts, styles, images, and
+ * data. Its `<title>`, else its first `<h1>`, becomes its title in the outline. The `artifact:`
+ * addresses it uses are returned to resolve, as a deck's are.
+ */
+export async function validatePage(
+  blobStorage: ArtifactBlobStorage,
+  files: readonly ArtifactFile[]
+): Promise<{
+  readonly entry: string
+  readonly outline: PageOutline
+  readonly references: readonly FoundReference[]
+}> {
+  const entry = files.find((file) => file.path === HTML_ENTRY)
+  if (!entry) {
+    throw invalidArtifact(
+      `A page needs '${HTML_ENTRY}', the page itself; put its scripts, styles, and data beside it.`
+    )
+  }
+  refuseFrameAssetPaths(files, "the page")
+  const html = await readArtifactText(blobStorage, entry, ARTIFACT_LIMITS.maxPageBytes)
+
+  let title = ""
+  let heading = ""
+  let readingHeading = false
+  const rewriter = new HTMLRewriter()
+    .on("title", {
+      text(chunk) {
+        title += chunk.text
+      },
+    })
+    .on("h1", {
+      element(element) {
+        if (heading || readingHeading) return
+        readingHeading = true
+        element.onEndTag(() => {
+          readingHeading = false
+          heading ||= " "
+        })
+      },
+      text(chunk) {
+        if (readingHeading) heading += chunk.text
+      },
+    })
+  const { references, refusal } = readHtmlReferences(rewriter, () => "")
+  rewriter.transform(html)
+
+  const refused = refusal()
+  if (refused) throw invalidArtifact(refused)
+  const plain = (text: string) => decodeHtmlEntities(text).replace(/\s+/g, " ").trim()
+  const named = plain(title) || plain(heading)
+  return {
+    entry: HTML_ENTRY,
+    outline: { kind: "page", ...(named ? { title: named.slice(0, 200) } : {}) },
+    references,
+  }
+}