@specbook/core 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The runner, mock engine, template engine and shared proxy behind Specbook: Storybook for APIs.",
   "keywords": [
     "specbook",

package/src/assert.ts

@@ -9,13 +9,24 @@ export const stripAnsi = (s: string) => s.replace(ANSI, '')
 /** Plain uvu/assert, for use outside a run. */
 export const assert = uvu as unknown as Assert
 
-function locate(stack: string | undefined): AssertionResult['location'] {
+const FRAME = /(?:\(|at )?([^\s()]+):(\d+):(\d+)\)?\s*$/
+
+/**
+ * Where in the user's code an assertion was made: the first frame of the stack that is not this helper. Run from source
+ * the helper is `core/src/assert`; inside a bundled CLI it is the bundle itself, so any frame in the file the stack starts
+ * in is the helper too.
+ */
+export function locate(stack: string | undefined): AssertionResult['location'] {
   if (!stack) return undefined
-  const lines = stack.split('\n').slice(1)
-  for (const line of lines) {
-    if (line.includes('/core/src/assert') || line.includes('node_modules')) continue
-    const m = /(?:\(|at )?([^\s()]+):(\d+):(\d+)\)?\s*$/.exec(line)
-    if (m) return { file: m[1] as string, line: Number(m[2]), column: Number(m[3]) }
+  const frames = stack
+    .split('\n')
+    .slice(1)
+    .map((line) => ({ line, m: FRAME.exec(line) }))
+  const own = frames[0]?.m?.[1]
+  for (const { line, m } of frames) {
+    if (!m || line.includes('/core/src/assert') || line.includes('node_modules')) continue
+    if (m[1] === own) continue
+    return { file: m[1] as string, line: Number(m[2]), column: Number(m[3]) }
   }
   return undefined
 }

package/src/config.ts

@@ -18,7 +18,12 @@ export interface EnvironmentConfig {
 export interface ServiceConfig<E extends string = string> {
   /** Path to an OpenAPI/Swagger file (relative to the config's project root). */
   spec: string
-  baseUrl: Partial<Record<E | 'live', string>>
+  /**
+   * Where calls go. A template over the environment's variables (`'{{petstoreUrl}}'`: config `vars`, then
+   * `environments.<env>.vars`, then `.specbook/environments/<env>.env`), which also makes `live` an
+   * environment; or one address per environment.
+   */
+  baseUrl: string | Partial<Record<E | 'live', string>>
   /** Default auth profile for this service. */
   auth?: string
 }
@@ -51,7 +56,10 @@ export interface BrandingConfig {
 
 export interface SpecbookConfig<E extends string = string> {
   project: string
-  /** Non-sensitive variables, safe to commit. */
+  /**
+   * Non-sensitive variables, safe to commit: the defaults every environment starts from. An environment
+   * overrides them in `environments.<env>.vars` or `.specbook/environments/<env>.env`.
+   */
   vars?: Record<string, unknown>
   environments?: Partial<Record<E, EnvironmentConfig>>
   /** Secret references; OSS resolves them from env vars / dotenv files. */
@@ -60,6 +68,11 @@ export interface SpecbookConfig<E extends string = string> {
   auth?: Record<string, AuthProfile>
   secretProviders?: SecretProvider[]
   faker?: FakerConfig
+  /**
+   * How long a request waits for an answer, in milliseconds, in a run from the command line or a browser. A request's own
+   * `timeoutMs` wins, and `specbook test --timeout` wins over this. 0 waits for as long as it takes. Default: 30 seconds.
+   */
+  timeoutMs?: number
   codegen?: { outDir?: string; importPrefix?: string }
   branding?: BrandingConfig
 }

package/src/controls.ts

@@ -26,24 +26,44 @@ interface SelectOpts<O, V> {
   default?: number | V | ((options: readonly O[]) => V)
 }
 
+/** A starting value, or a function that makes one each time it is needed (a faker value, today's date). */
+export type Default<T> = T | (() => T)
+
+/** Whether a control's starting value is made fresh each time, so a UI can offer to make another. */
+export const isGenerated = (ctl: Control): boolean => typeof ctl.opts.default === 'function'
+
+function startingValue<T>(d: Default<T> | undefined): T | undefined {
+  return typeof d === 'function' ? (d as () => T)() : d
+}
+
 export const c = {
-  text: (o: { default?: string; label?: string; description?: string } = {}): Control<string> => ({
+  text: (
+    o: { default?: Default<string>; label?: string; description?: string } = {},
+  ): Control<string> => ({
     kind: 'text',
     opts: o,
   }),
   number: (
-    o: { default?: number; min?: number; max?: number; label?: string; description?: string } = {},
+    o: {
+      default?: Default<number>
+      min?: number
+      max?: number
+      label?: string
+      description?: string
+    } = {},
   ): Control<number> => ({
     kind: 'number',
     opts: o,
   }),
   boolean: (
-    o: { default?: boolean; label?: string; description?: string } = {},
+    o: { default?: Default<boolean>; label?: string; description?: string } = {},
   ): Control<boolean> => ({
     kind: 'boolean',
     opts: o,
   }),
-  date: (o: { default?: string; label?: string; description?: string } = {}): Control<string> => ({
+  date: (
+    o: { default?: Default<string>; label?: string; description?: string } = {},
+  ): Control<string> => ({
     kind: 'date',
     opts: o,
   }),
@@ -105,7 +125,9 @@ export function resolveControl(name: string, ctl: Control, given: unknown): unkn
       )
         return values[d]
       if (typeof d === 'function') return d(options)
-      if (d !== undefined) return d
+      // a starting value that is not one of the options means nothing (`default: 0` on pet ids is the first pet, not a
+      // pet numbered 0): the first option is the default
+      if (d !== undefined && values.some((v) => same(v, d))) return d
       return values[0]
     }
     case 'multiselect': {
@@ -132,11 +154,11 @@ export function resolveControl(name: string, ctl: Control, given: unknown): unkn
       return v.map((item) => resolveControl(name, ctl.opts.item, item))
     }
     case 'boolean':
-      return given ?? ctl.opts.default ?? false
+      return given ?? startingValue(ctl.opts.default) ?? false
     case 'number':
-      return given ?? ctl.opts.default ?? 0
+      return given ?? startingValue(ctl.opts.default) ?? 0
     default:
-      return given ?? ctl.opts.default ?? ''
+      return given ?? startingValue(ctl.opts.default) ?? ''
   }
 }
 
@@ -161,7 +183,10 @@ export function describeControls(controls: Controls) {
         }))
         return [k, { kind: ctl.kind, options }]
       }
-      return [k, { kind: ctl.kind, default: ctl.opts.default }]
+      return [
+        k,
+        { kind: ctl.kind, default: startingValue(ctl.opts.default), generated: isGenerated(ctl) },
+      ]
     }),
   )
 }

package/src/diff.ts

@@ -0,0 +1,131 @@
+// A line diff for a failed assertion, shared by the command line and the UI so both show the same thing.
+
+import type { AssertionResult } from './types'
+
+export type DiffLine =
+  | { kind: 'same' | 'expected' | 'received'; text: string }
+  /** a run of unchanged lines left out */
+  | { kind: 'skip'; text: string }
+
+const STATUS_TEXT: Record<number, string> = {
+  200: 'OK',
+  201: 'Created',
+  202: 'Accepted',
+  204: 'No Content',
+  301: 'Moved Permanently',
+  302: 'Found',
+  304: 'Not Modified',
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  410: 'Gone',
+  422: 'Unprocessable Entity',
+  429: 'Too Many Requests',
+  500: 'Internal Server Error',
+  501: 'Not Implemented',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+}
+
+export const statusText = (status: number): string => STATUS_TEXT[status] ?? ''
+
+/** A value as lines: strings as JSON (multi-line text as it is), everything else pretty-printed JSON. */
+function show(v: unknown): string[] {
+  if (typeof v === 'string') return v.includes('\n') ? v.split('\n') : [JSON.stringify(v)]
+  if (v === undefined) return ['undefined']
+  try {
+    return (JSON.stringify(v, null, 2) ?? String(v)).split('\n')
+  } catch {
+    return [String(v)]
+  }
+}
+
+/** Lines in common stay; the rest are `expected` (only in a) or `received` (only in b). */
+function lineDiff(a: string[], b: string[]): DiffLine[] {
+  const out: DiffLine[] = []
+  // very large values are not worth a quadratic table: show one against the other
+  if (a.length * b.length > 250_000) {
+    for (const text of a) out.push({ kind: 'expected', text })
+    for (const text of b) out.push({ kind: 'received', text })
+    return out
+  }
+  const n = a.length
+  const m = b.length
+  const table = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1))
+  for (let i = n - 1; i >= 0; i--)
+    for (let j = m - 1; j >= 0; j--)
+      (table[i] as Uint32Array)[j] =
+        a[i] === b[j]
+          ? ((table[i + 1] as Uint32Array)[j + 1] as number) + 1
+          : Math.max(
+              (table[i + 1] as Uint32Array)[j] as number,
+              (table[i] as Uint32Array)[j + 1] as number,
+            )
+  let i = 0
+  let j = 0
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      out.push({ kind: 'same', text: a[i] as string })
+      i++
+      j++
+    } else if (
+      ((table[i + 1] as Uint32Array)[j] as number) >= ((table[i] as Uint32Array)[j + 1] as number)
+    ) {
+      out.push({ kind: 'expected', text: a[i++] as string })
+    } else {
+      out.push({ kind: 'received', text: b[j++] as string })
+    }
+  }
+  while (i < n) out.push({ kind: 'expected', text: a[i++] as string })
+  while (j < m) out.push({ kind: 'received', text: b[j++] as string })
+  return out
+}
+
+/** Keeps the changed lines and `context` lines around them; longer runs of unchanged lines become one `skip` line. */
+function collapse(lines: DiffLine[], context: number): DiffLine[] {
+  const keep = new Array<boolean>(lines.length).fill(false)
+  lines.forEach((l, i) => {
+    if (l.kind === 'same') return
+    for (let k = Math.max(0, i - context); k <= Math.min(lines.length - 1, i + context); k++)
+      keep[k] = true
+  })
+  const out: DiffLine[] = []
+  let skipped = 0
+  const flush = () => {
+    if (skipped > 0)
+      out.push({ kind: 'skip', text: `… ${skipped} unchanged line${skipped > 1 ? 's' : ''}` })
+    skipped = 0
+  }
+  lines.forEach((l, i) => {
+    if (keep[i]) {
+      flush()
+      out.push(l)
+    } else skipped++
+  })
+  flush()
+  return out
+}
+
+/**
+ * What a failed assertion expected and what it received, as diff lines: the status check reads as one pair of lines, values
+ * are compared line by line, and an assertion that recorded only a diff string shows that.
+ */
+export function diffAssertion(a: AssertionResult, context = 3): DiffLine[] {
+  if (a.operator === 'status') {
+    const got =
+      typeof a.actual === 'number' ? `${a.actual} ${statusText(a.actual)}`.trim() : String(a.actual)
+    return [
+      { kind: 'expected', text: `status ${a.expected}` },
+      { kind: 'received', text: `status ${got}` },
+    ]
+  }
+  if ('expected' in a || 'actual' in a)
+    return collapse(lineDiff(show(a.expected), show(a.actual)), context)
+  if (a.diff) return a.diff.split('\n').map((text) => ({ kind: 'same', text }))
+  return []
+}

package/src/environment.ts

@@ -0,0 +1,175 @@
+// Where an environment's calls go: base URLs and sign-in endpoints are templates over the environment's
+// variables (config `vars`, then `environments.<env>.vars`, then the environment's own file).
+
+import type { SpecbookConfig } from './config'
+import type { OAuthSettings } from './oauth'
+import {
+  collectPlaceholders,
+  isDeferred,
+  isFakerName,
+  renderString,
+  TemplateError,
+} from './template'
+
+/** An address (base URL or sign-in endpoint) that cannot be worked out for an environment. */
+export class AddressError extends Error {
+  constructor(
+    message: string,
+    /** the variable to set, when that is what is missing */
+    readonly variable?: string,
+  ) {
+    super(message)
+    this.name = 'AddressError'
+  }
+}
+
+type AddressConfig = Pick<SpecbookConfig, 'vars' | 'environments' | 'services'> & {
+  auth?: Record<string, { oauth?: OAuthSettings }>
+}
+
+/** Fields of an OAuth profile that are templates; `scopes` and the rest stay as written. */
+export const OAUTH_ADDRESS_FIELDS = [
+  'authorizationUrl',
+  'tokenUrl',
+  'openIdConnectUrl',
+  'clientId',
+] as const
+
+/**
+ * The variables an environment's addresses are rendered with, later wins:
+ * config `vars` → `environments.<env>.vars` → the environment's file (→ browser store, via `extra`).
+ * Per-run values (overrides, captures) deliberately take no part: the dev server has to reach the same
+ * answer as the page.
+ */
+export function environmentScope(
+  cfg: Pick<SpecbookConfig, 'vars' | 'environments'>,
+  env: string,
+  fileVars: Record<string, unknown> = {},
+  extra: Record<string, unknown> = {},
+): Record<string, unknown> {
+  return {
+    ...cfg.vars,
+    ...(cfg.environments as Record<string, { vars?: Record<string, unknown> }> | undefined)?.[env]
+      ?.vars,
+    ...fileVars,
+    ...extra,
+  }
+}
+
+/** Renders an address template with plain variables only; secrets and faker values have no place in one. */
+function renderAddress(template: string, scope: Record<string, unknown>, what: string): string {
+  for (const name of collectPlaceholders(template)) {
+    if (isDeferred(name) || isFakerName(name))
+      throw new AddressError(
+        `${what} cannot use {{${name}}}: only environment variables are available`,
+      )
+  }
+  let value: unknown
+  try {
+    value = renderString(template, scope)
+  } catch (e) {
+    if (e instanceof TemplateError) throw new AddressError(`${what}: set ${e.variable}`, e.variable)
+    throw e
+  }
+  if (value !== null && typeof value === 'object')
+    throw new AddressError(`${what} is not a text value`)
+  const out = value === undefined || value === null ? '' : String(value).trim()
+  if (/\{\{/.test(out)) throw new AddressError(`${what} still contains a placeholder: ${out}`)
+  return out
+}
+
+/**
+ * The address calls for `service` go to in `env`, without a trailing slash; `undefined` when there is none.
+ * A string `baseUrl` is a template over `scope`; a record is read by environment name (and may use variables
+ * too).
+ */
+export function baseUrlFor(
+  cfg: Pick<SpecbookConfig, 'services'>,
+  service: string,
+  env: string,
+  scope: Record<string, unknown>,
+): string | undefined {
+  const base = cfg.services[service]?.baseUrl as
+    | string
+    | Record<string, string | undefined>
+    | undefined
+  const template = typeof base === 'string' ? base : base?.[env]
+  if (!template) return undefined
+  const what = `No base URL for ${service} in ${env}`
+  const url = /\{\{/.test(template) ? renderAddress(template, scope, what) : template.trim()
+  return url ? url.replace(/\/+$/, '') : undefined
+}
+
+/** `oauth` with its address fields rendered; `scopes` and everything else as written. */
+export function oauthFor<T extends OAuthSettings>(
+  oauth: T,
+  scope: Record<string, unknown>,
+  profile = 'sign-in',
+): T {
+  const out: Record<string, unknown> = { ...oauth }
+  for (const field of OAUTH_ADDRESS_FIELDS) {
+    const v = out[field]
+    if (typeof v !== 'string' || !/\{\{/.test(v)) continue
+    const rendered = renderAddress(v, scope, `${profile} ${field}`)
+    if (rendered) out[field] = rendered
+    else delete out[field]
+  }
+  return out as T
+}
+
+/**
+ * Every environment name, in the order the pickers show them: `mock`, `live` (when a service has a string
+ * `baseUrl` or a `live` address), the record keys, `environments`, then environment files and `extra` (the
+ * browser's own environments).
+ */
+export function environmentNames(
+  cfg: Pick<SpecbookConfig, 'environments' | 'services'>,
+  fileEnvs: Iterable<string> = [],
+  extra: Iterable<string> = [],
+): string[] {
+  const names = new Set<string>(['mock'])
+  const services = Object.values(cfg.services ?? {})
+  if (services.some((s) => typeof s.baseUrl === 'string')) names.add('live')
+  for (const s of services) {
+    if (s.baseUrl && typeof s.baseUrl === 'object')
+      for (const k of Object.keys(s.baseUrl)) names.add(k)
+  }
+  for (const k of Object.keys(cfg.environments ?? {})) names.add(k)
+  for (const k of fileEnvs) names.add(k)
+  for (const k of extra) names.add(k)
+  return [...names]
+}
+
+/** True when `url` is an absolute http(s) address. */
+export const isAbsoluteHttp = (url: string): boolean => /^https?:\/\/[^\s/]/i.test(url)
+
+export interface AddressUse {
+  services: string[]
+  profiles: { profile: string; field: (typeof OAUTH_ADDRESS_FIELDS)[number] }[]
+}
+
+/** Which base URLs and sign-in fields read each variable: what a variable is "for" in an environment. */
+export function addressUses(cfg: AddressConfig): Record<string, AddressUse> {
+  const out: Record<string, AddressUse> = {}
+  const use = (name: string) => {
+    if (isDeferred(name) || isFakerName(name)) return undefined
+    out[name] ??= { services: [], profiles: [] }
+    return out[name]
+  }
+  for (const [service, s] of Object.entries(cfg.services ?? {})) {
+    const templates = typeof s.baseUrl === 'string' ? [s.baseUrl] : Object.values(s.baseUrl ?? {})
+    for (const t of templates)
+      for (const name of collectPlaceholders(t)) {
+        const u = use(name)
+        if (u && !u.services.includes(service)) u.services.push(service)
+      }
+  }
+  for (const [profile, p] of Object.entries(cfg.auth ?? {})) {
+    for (const field of OAUTH_ADDRESS_FIELDS) {
+      const v = (p.oauth as Record<string, unknown> | undefined)?.[field]
+      if (typeof v !== 'string') continue
+      for (const name of collectPlaceholders(v)) use(name)?.profiles.push({ profile, field })
+    }
+  }
+  return out
+}

package/src/index.ts

@@ -1,6 +1,8 @@
 export { assert, createAsserter, stripAnsi } from './assert'
 export * from './config'
 export * from './controls'
+export * from './diff'
+export * from './environment'
 export type { Example, ExampleLoader, FileReader, Row } from './example'
 export { fromFormRows, fromRows, toFormRows, toRows } from './example'
 export type { FakerConfig } from './faker'
@@ -9,7 +11,7 @@ export * from './mock'
 export * from './oauth'
 export * from './proxy/index'
 export * from './reporters/index'
-export { defineOperation, request } from './request'
+export { defineOperation, request, withMock } from './request'
 export * from './runner/index'
 export * from './secrets'
 export type { Sequence, SequenceMeta, StepCtx, StepNode } from './sequence'
@@ -18,6 +20,7 @@ export type { SnippetInput, SnippetLang } from './snippets'
 export { snippetLangs, toSnippet } from './snippets'
 export {
   authFromSpec,
+  environmentsFromServers,
   type JsonAuthProfile,
   liveBaseUrl,
   MAX_SERVERS,
@@ -30,6 +33,7 @@ export {
   deepMerge,
   render,
   renderString,
+  rootName,
   TemplateError,
   usesFaker,
 } from './template'