Skip to content

AI-native design editor. Open-source Figma alternative.

12.7 KB
Raw Blame
import { uniq } from 'es-toolkit/array'
import * as v from 'valibot'

// Figma's plugin API validates arguments with Zod 4 and words what it refuses in its own way
// (Figma desktop 126). OpenPencil checks them with Valibot; this module words the issues as Figma
// does, so a script sees the message it would see in Figma.

/** Figma's message for a value its schema rejects. */
export function invalid(method: string, problem: string, property = 'value'): Error {
  return new Error(`in ${method}: Property "${property}" failed validation: ${problem}`)
}

export function received(value: unknown): string {
  // Figma names NaN and the infinities rather than calling them numbers.
  if (typeof value === 'number' && !Number.isFinite(value)) return String(value)
  if (Array.isArray(value)) return 'array'
  return value === null ? 'null' : typeof value
}

/**
 * The values in one of Valibot's `expected` texts, such as `("A" | "B")` for a picklist or `"A"`
 * for a literal, which Figma lists without Valibot's grouping.
 */
function expectedValues(expected: string | null | undefined): string[] {
  return [...(expected ?? '').matchAll(/"([^"]*)"/g)].map((match) => match[1])
}

/** A value outside a fixed list of options. */
function invalidOption(expected: string | null | undefined, at = ''): string {
  const options = expectedValues(expected).map((option) => `"${option}"`)
  return `Invalid option: expected one of ${options.join('|')}${at}`
}

export function tooSmall(minimum: number, at = ''): string {
  return `Too small: expected number to be >=${minimum}${at}`
}

function tooBig(maximum: number, at = ''): string {
  return `Too big: expected number to be <=${maximum}${at}`
}

/** A choice between shapes that none of them matches, each listing its own problem. */
function noneMatched(problems: readonly string[], at = ''): string {
  const expected = at
    ? `Expected ${at} to be one of the following`
    : 'Expected one of the following'
  return `${expected}, but none matched:\n${problems.map((problem) => indent(problem)).join('\n')}`
}

/** `text` two spaces in, every line of it, so a choice inside a choice keeps its depth. */
function indent(text: string): string {
  return text.replaceAll(/^/gm, '  ')
}

// --- Reading a schema at an issue's path ---

type Schema = v.GenericSchema
type PathItem = v.IssuePathItem

function property(target: unknown, key: string): unknown {
  return target && typeof target === 'object' ? Reflect.get(target, key) : undefined
}

function isSchema(value: unknown): value is Schema {
  return !!value && typeof value === 'object' && 'kind' in value && '~run' in value
}

function schemaProperty(target: unknown, key: string): Schema | undefined {
  const value = property(target, key)
  return isSchema(value) ? value : undefined
}

/** A picklist's options, or a union's or variant's: the values or schemas it chooses from. */
function listProperty(target: unknown, key: string): readonly unknown[] {
  const value = property(target, key)
  return Array.isArray(value) ? value : []
}

/** The schema under a pipe or an optional wrapper, which decides what a value must be. */
function base(schema: Schema): Schema {
  const [first] = listProperty(schema, 'pipe')
  if (isSchema(first) && first !== schema) return base(first)
  const wrapped = schemaProperty(schema, 'wrapped')
  return wrapped ? base(wrapped) : schema
}

function entries(schema: Schema): Partial<Record<string, Schema>> {
  const value = property(base(schema), 'entries')
  if (!value || typeof value !== 'object') return {}
  return Object.fromEntries(Object.entries(value).filter(([, entry]) => isSchema(entry)))
}

function options(schema: Schema): readonly Schema[] {
  return listProperty(base(schema), 'options').filter(isSchema)
}

/** The option of a variant that `input`'s discriminator picks. */
function variantOption(schema: Schema, input: unknown): Schema | undefined {
  const key = property(base(schema), 'key')
  if (typeof key !== 'string') return undefined
  const value = property(input, key)
  return options(schema).find((option) => v.is(entries(option)[key] ?? v.never(), value))
}

/** The schema a step down `item` leads to from `schema`. */
function child(schema: Schema, item: PathItem): Schema | undefined {
  const own = base(schema)
  if (own.type === 'variant') {
    const option = variantOption(own, item.input)
    return option && child(option, item)
  }
  if (own.type === 'array') return schemaProperty(own, 'item')
  if (own.type === 'record') return schemaProperty(own, 'value')
  return entries(own)[String(item.key)]
}

function schemaAt(root: Schema, path: readonly PathItem[]): Schema | undefined {
  let schema: Schema | undefined = root
  for (const item of path) schema = schema && child(schema, item)
  return schema
}

// --- Wording ---

/** Where Figma reports an issue: an array item by its index, a field by its path. */
function where(path: readonly PathItem[]): string {
  if (path.length === 0) return ''
  const [first] = path
  if (path.length === 1 && typeof first.key === 'number') return ` at index ${first.key}`
  return ` at ${pathText(path)}`
}

function pathText(path: readonly PathItem[]): string {
  return path
    .map((item) => (typeof item.key === 'number' ? `[${item.key}]` : `.${String(item.key)}`))
    .join('')
}

/** What Figma calls the value each schema expects. */
const EXPECTED: Partial<Record<string, string>> = {
  strict_object: 'object',
  loose_object: 'object',
  object: 'object',
  variant: 'object',
  array: 'array',
  record: 'record',
  number: 'number',
  string: 'string',
  boolean: 'boolean',
  null: 'null'
}

/**
 * A field left out. Zod checks it as undefined, so an option or literal is refused as such and
 * anything else as missing; Valibot reports it against the key, so its schema says which.
 */
function missing(schema: Schema | undefined, path: readonly PathItem[]): string {
  const own = schema && base(schema)
  if (own?.type === 'picklist') return invalidOption(own.expects, where(path))
  if (own?.type === 'literal') return `Invalid input: expected ${own.expects}${where(path)}`
  return `Required value missing${where(path)}`
}

/**
 * Every key of `input` the object schema does not know, in one line as Figma lists them. Valibot
 * stops at the first; without the schema, only that one is named.
 */
function unrecognized(
  schema: Schema | undefined,
  input: unknown,
  first: unknown,
  at: string
): string {
  // A variant's keys are those of the option the input's discriminator picks.
  const object = schema && base(schema).type === 'variant' ? variantOption(schema, input) : schema
  const known = object ? entries(object) : {}
  // Valibot reads keys with `for...in`, inherited ones too; any it reports is named.
  const own = Object.keys(input && typeof input === 'object' ? input : {})
  const keys = uniq([...own, String(first)]).filter((key) => !Object.hasOwn(known, key))
  const names = keys.map((key) => `"${key}"`).join(', ')
  return `${keys.length === 1 ? 'Unrecognized key' : 'Unrecognized keys'}: ${names}${at}`
}

/** Figma's line for a number outside its bounds, or a check's own message; null for others. */
function refinementLine(issue: v.BaseIssue<unknown>, at: string): string | null {
  switch (issue.type) {
    case 'min_value':
      return tooSmall(Number(issue.requirement), at)
    case 'max_value':
      return tooBig(Number(issue.requirement), at)
    case 'integer':
      return `Expected int, received number${at}`
    case 'finite':
      return `Expected number, received ${received(issue.input)}${at}`
    case 'check':
    case 'raw_check':
      return `${issue.message}${at}`
    default:
      return null
  }
}

/**
 * One of Figma's lines for an issue. Its path, relative to `root`, finds the schemas involved;
 * `prefix` places `root` in the value the script passed, for where the line says it is.
 */
function line(issue: v.BaseIssue<unknown>, root: Schema, prefix: readonly PathItem[]): string {
  const relative = issue.path ?? []
  const path = [...prefix, ...relative]
  const last = relative.at(-1)
  if (last?.origin === 'key') {
    if (issue.expected === 'never') {
      const parent = relative.slice(0, -1)
      return unrecognized(schemaAt(root, parent), last.input, last.key, where(path.slice(0, -1)))
    }
    return missing(schemaAt(root, relative), path)
  }
  switch (issue.type) {
    // A variant refuses an object by its discriminator, anything else as not an object.
    case 'variant': {
      const variant = schemaAt(root, relative.slice(0, -1))
      if (!last || !variant || property(base(variant), 'key') !== last.key) break
      const values = expectedValues(issue.expected).join(', ')
      return `Expected ${pathText(path.slice(0, -1))}.${String(last.key)} to be one of the following: ${values}`
    }
    case 'picklist':
      return invalidOption(issue.expected, where(path))
    // Valibot quotes the string a literal expects, as Figma does.
    case 'literal':
      return `Invalid input: expected ${issue.expected}${where(path)}`
  }
  const refinement = refinementLine(issue, where(path))
  if (refinement) return refinement
  if (issue.input === undefined) return `Required value missing${where(path)}`
  return `Expected ${EXPECTED[issue.type] ?? issue.type}, received ${received(issue.input)}${where(path)}`
}

/**
 * Whether a shape matched but for checks on its values, such as a bound, an integer, or a key it
 * does not know, so a choice settles on it. Valibot counts a key left out and a number that is not
 * finite as matching too; Zod, and so Figma, refuses those as the wrong type.
 */
function matchedButForChecks(issues: readonly v.BaseIssue<unknown>[]): boolean {
  return issues.every((issue) =>
    issue.kind === 'validation'
      ? issue.type !== 'finite'
      : issue.path?.at(-1)?.origin === 'key' && issue.expected === 'never'
  )
}

/**
 * Figma's lines for `value` against `schema`, empty when it passes. A choice between shapes that
 * fails is worded as Zod words it: the one shape that matched but for checks on its values reports
 * alone; otherwise every shape reports, several problems of one shape grouped.
 */
function figmaProblems(schema: Schema, value: unknown, prefix: readonly PathItem[] = []): string[] {
  const own = base(schema)
  if (own.type !== 'union') {
    const result = v.safeParse(schema, value)
    return result.success ? [] : wordIssues(schema, result.issues, prefix)
  }
  const branches = options(own).map((option) => ({ option, result: v.safeParse(option, value) }))
  const failed = branches.flatMap(({ option, result }) =>
    result.success ? [] : [{ option, issues: result.issues }]
  )
  if (failed.length < branches.length) return []
  const settled = failed.filter(({ issues }) => matchedButForChecks(issues))
  if (settled.length === 1) return wordIssues(settled[0].option, settled[0].issues, prefix)
  // Shapes that fail alike, as every shape fails a missing value, read once.
  const lines = failed.map(({ option, issues }) => {
    const problems = wordIssues(option, issues, prefix)
    return problems.length === 1
      ? (problems[0] ?? '')
      : `Multiple issues${where(prefix)}:\n${problems.map((text) => indent(text)).join('\n')}`
  })
  return [noneMatched(uniq(lines), pathText(prefix))]
}

/** Figma's lines for the issues `schema` found; a choice nested in it is worded from where it sits. */
function wordIssues(
  schema: Schema,
  issues: readonly v.BaseIssue<unknown>[],
  prefix: readonly PathItem[]
): string[] {
  return issues.map((issue) => {
    const nested = issue.type === 'union' ? schemaAt(schema, issue.path ?? []) : undefined
    if (!nested) return line(issue, schema, prefix)
    return figmaProblems(nested, issue.input, [...prefix, ...(issue.path ?? [])]).join('\n')
  })
}

/** A line from an issue alone, a choice listing what each of its shapes found. */
function fallback(issue: v.BaseIssue<unknown>, root: Schema): string {
  if (issue.type !== 'union' || !issue.issues) return line(issue, root, [])
  return noneMatched(uniq(issue.issues.map((nested) => line(nested, root, []))))
}

function rereadProblems(schema: Schema, value: unknown): string[] {
  try {
    return figmaProblems(schema, value)
  } catch {
    return []
  }
}

/**
 * `value` as `schema` reads it, each field read once, or Figma's refusal of it from `method` for
 * `property`.
 */
export function parseFigma<const S extends Schema>(
  schema: S,
  value: unknown,
  method: string,
  property = 'value'
): v.InferOutput<S> {
  const result = v.safeParse(schema, value)
  if (result.success) return result.output
  // Wording a choice reads the value again; a value that reads differently the second time, or
  // throws, still reports what the first read found.
  const problems = rereadProblems(schema, value)
  const lines =
    problems.length > 0 ? problems : result.issues.map((issue) => fallback(issue, schema))
  throw invalid(method, lines.join('\n'), property)
}