@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/vite-plugin/src/options.ts

@@ -0,0 +1,641 @@
+/**
+ * The plugin's options, read once when the plugin is made, each value checked
+ * before the plugin does anything with it.
+ *
+ * A JavaScript config is not type-checked, so an option can hold a value of
+ * any kind, and an object of options a key of any name. Only an omitted
+ * option (`undefined`) is one not given: every value given is checked, on
+ * every canister, with a `didFile` or not, and whether or not a run would use
+ * it, and quoted in a message by `describeValue`, which never throws. So is
+ * every key: one that is no option (a misspelled `canister`, `didfile` or
+ * `canisterID`) is refused whatever its value, `undefined` included, and the
+ * message names the option it may misspell. Never read, it would start the
+ * plugin with no canister, take a canister for one only named in the cookie,
+ * or generate one without its ID, without a word.
+ *
+ * - An option of the whole plugin (`canisters`, `injectEnvironment`,
+ *   `failOnError`, `onGenerated`) that is not one throws when the config
+ *   loads, and so does a key of the options that is none of them: read by a
+ *   guess, the options could ship stale bindings or drop the local
+ *   environment.
+ * - A canister whose options hold a value that is not one, or a key that is
+ *   no option, is refused. Every run fails it, with the reasons, before the
+ *   run does anything else: it fetches nothing, writes nothing, runs no
+ *   `meant` process and makes no request for it, and the other
+ *   canisters run as they would. Its name is still in the `ic_env` cookie,
+ *   which carries every canister an entry names: the app may still call it.
+ *
+ * Each option is read once, here: a getter runs once, and one that throws
+ * refuses its canister. What the plugin keeps is a copy of what was read.
+ *
+ * Only `undefined` selects an option's default: every default here is chosen
+ * by `=== undefined`, never by `??` or `||`, which would take `null` (or `0`,
+ * `""`, `false`) for an option not given. Each value but `undefined` is
+ * checked first, and one that is not a value of the option is refused.
+ *
+ * Every object of options (the options, `canisters`, each canister's entry,
+ * a `network` of `{ host }`) is a plain object: one whose prototype is
+ * `Object.prototype` or `null`. A `Map`, a `Promise`, an instance of a class
+ * or an object that inherits from another is refused as any other value that
+ * is not one: read for its keys, a `Map` of canisters or a `Promise` of
+ * options would be read as none. Its keys are its own enumerable string keys,
+ * as `Object.keys` lists them (which runs no getter): each key of the
+ * options, of an entry and of a network is one of its type's options, and
+ * each key of `canisters` a canister's name.
+ *
+ * A canister's name is its name in the `icp` project, kept as given:
+ * `__proto__`, `constructor` and `toString` name canisters as any other name
+ * does. What the plugin keeps by canister name is kept in a `Map`, never in a
+ * plain object, where such a name would reach `Object.prototype` (an
+ * assignment to `__proto__` sets the prototype, and a lookup of `toString`
+ * finds a function). A name the `ic_env` cookie cannot carry
+ * (`cookieCarries`: every name `icp` gives a canister is one it carries) is
+ * left out of the cookie, with a warning.
+ */
+
+import { describeError, describeValue } from "./describe-value.js"
+import { cookieCarries } from "./env.js"
+import { resolveNetwork, type CanisterNetwork } from "./fetch.js"
+import type { IcReactorPluginOptions } from "./index.js"
+import { isPrincipalText } from "./principal-text.js"
+
+/** Where a canister's module goes when it sets no `outDir`. */
+export const DEFAULT_OUT_DIR = "src/canisters"
+
+/** A canister's entry, as the options' type gives it. */
+type CanisterEntry = NonNullable<IcReactorPluginOptions["canisters"]>[string]
+
+/**
+ * The options of `icReactor()`, of a canister's entry and of a `network` of
+ * `{ host }`, in the order of their types. Each is checked against its type
+ * (`satisfies`): an option the type gains, or loses, fails the type check
+ * until it is listed here, so no option the type allows is refused.
+ */
+const PLUGIN_OPTIONS = Object.keys({
+  canisters: true,
+  injectEnvironment: true,
+  failOnError: true,
+  onGenerated: true,
+} satisfies Record<keyof IcReactorPluginOptions, true>)
+const CANISTER_OPTIONS = Object.keys({
+  didFile: true,
+  outDir: true,
+  canisterId: true,
+  network: true,
+  methods: true,
+  verify: true,
+} satisfies Record<keyof CanisterEntry, true>)
+const NETWORK_OPTIONS = Object.keys({
+  host: true,
+} satisfies Record<
+  keyof Extract<NonNullable<CanisterEntry["network"]>, object>,
+  true
+>)
+
+/** A canister with a `.did` to generate from: its options, every one checked. */
+export interface Generated {
+  name: string
+  didFile: string
+  outDir: string
+  /** The live canister its `didFile` is fetched from when it is not on disk. */
+  canisterId?: string
+  network?: CanisterNetwork
+  /** The methods a fetched `didFile` is projected to. */
+  methods?: readonly string[]
+  verify?: "live"
+}
+
+/** A canister whose options cannot be used, and why. */
+export interface Refused {
+  name: string
+  /**
+   * Every reason: a key of its entry that is no option first, then each
+   * option's, in the order of the options.
+   */
+  problem: string
+  /**
+   * Its `didFile`, when that is a path. Canisters that share a `didFile` to
+   * be fetched share its fetch, so a refused one refuses it for them all.
+   */
+  didFile?: string
+  /** Whether it gave a `canisterId`, of any value, as a canister to fetch from does. */
+  givesCanisterId: boolean
+}
+
+/** The plugin's options as read and checked. */
+export interface ReadOptions {
+  injectEnvironment: boolean
+  failOnError: boolean | undefined
+  /** Called after each module a run generates; checked to be a function. */
+  onGenerated: IcReactorPluginOptions["onGenerated"]
+  /**
+   * Every canister an entry names, which the `ic_env` cookie carries: all but
+   * those of `uncarriedNames`.
+   */
+  names: string[]
+  /**
+   * The canisters an entry names that the cookie cannot carry
+   * (`cookieCarries`), which it leaves out, with a warning. They are
+   * generated, and refused, as any other.
+   */
+  uncarriedNames: string[]
+  /**
+   * The cookie's ID of each canister whose `canisterId` is one, by canister
+   * name: a `Map`, so that any name is kept as given.
+   */
+  configuredCanisterIds: Map<string, string>
+  /** `name: value` for each `canisterId` given that is not one. */
+  notCanisterIds: string[]
+  /** The canisters with a `didFile` whose options are all values. */
+  generated: Generated[]
+  /**
+   * The canisters that are refused: one whose options hold a value that is
+   * not one, with a `didFile` or not, and one whose options cannot be read.
+   */
+  refused: Refused[]
+}
+
+/**
+ * An object of options, as the options, `canisters`, each canister's entry
+ * and a `network` of `{ host }` are: a plain object, whose prototype is
+ * `Object.prototype` or `null`, as an object written `{ … }` and those that
+ * `JSON.parse`, `Object.fromEntries` and `Object.create(null)` make are. Not
+ * `null`, a list or a function, nor an object of a class (a `Map`, a
+ * `Promise`, a `Date`, a boxed string, a class's instance) or one that
+ * inherits from another object: read as options, a `Map`'s entries and a
+ * `Promise`'s value are none, so its canisters or its options would be left
+ * out without a word. Never throws: a proxy is asked for its prototype, and
+ * one that throws (a revoked one) is not a plain object.
+ */
+function isOptionsObject(value: unknown): value is Record<string, unknown> {
+  try {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return false
+    }
+    const prototype: unknown = Object.getPrototypeOf(value)
+    return prototype === Object.prototype || prototype === null
+  } catch {
+    // A revoked proxy, or a proxy's trap that throws.
+    return false
+  }
+}
+
+/**
+ * `value`, which is not a plain object, as a message quotes it.
+ * `describeValue` names an object's class (`Map {}`, `Promise {}`,
+ * `Ledger {…}`), but quotes one whose prototype has no class to name as it
+ * quotes a plain object, `{…}`: the quote then says that it inherits.
+ */
+function describeNotPlain(value: unknown): string {
+  const quoted = describeValue(value)
+  return quoted.startsWith("{")
+    ? `${quoted} (an object that inherits from another)`
+    : quoted
+}
+
+/** `value` as a path to read or write, relative to the Vite root. */
+const isPath = (value: unknown): value is string =>
+  typeof value === "string" && value !== "" && !value.includes("\0")
+
+/**
+ * Why a boolean option is not one, or `undefined` when it is omitted or a
+ * boolean. Read by truthiness, `0`, `""` or `null` would turn the option off
+ * and `"false"` would turn it on, without a word.
+ */
+export function booleanProblem(
+  name: string,
+  value: unknown
+): string | undefined {
+  if (value === undefined || typeof value === "boolean") return undefined
+  return (
+    `[ic-reactor] ${name} is ${describeValue(value)}, not true or false: ` +
+    `set it to true or false, or remove it for the default`
+  )
+}
+
+/** Why `methods` cannot be projected to, or `undefined` when it can. */
+export function methodsProblem(methods: unknown): string | undefined {
+  if (methods === undefined) return undefined
+  if (!Array.isArray(methods)) {
+    return `methods is ${describeValue(methods)}, not a list of method names`
+  }
+  if (methods.length === 0) {
+    return "methods is empty: name the methods the app calls, or remove methods for the whole interface"
+  }
+  for (const name of methods as unknown[]) {
+    if (typeof name !== "string" || name === "") {
+      return `methods holds ${describeValue(name)}, which is not a method name`
+    }
+    if (name.includes(",")) {
+      return `methods names ${describeValue(name)}, which has a comma: \`meant project\` takes the names separated by commas, so it cannot be projected to`
+    }
+  }
+  return undefined
+}
+
+/**
+ * Why `verify` is not an option value, or `undefined` when it is: omitted, or
+ * `"live"`.
+ */
+export function verifyProblem(verify: unknown): string | undefined {
+  if (verify === undefined || verify === "live") return undefined
+  return `verify is ${describeValue(verify)}, not "live": set it to "live" for the live check, or remove it for none`
+}
+
+/**
+ * Why `canisterId` is not a canister ID, or `undefined` when it is one or is
+ * omitted. A canister ID is the text of a principal, which is told here, and
+ * not only by the fetch or the check that reads it: those load
+ * `@icp-sdk/core`, and a canister with `methods` would have its methods
+ * listed, by a `meant` process, before its check found the ID wrong.
+ */
+export function canisterIdProblem(canisterId: unknown): string | undefined {
+  if (canisterId === undefined) return undefined
+  if (typeof canisterId !== "string" || canisterId === "") {
+    return `canisterId is ${describeValue(canisterId)}, not a canister ID: give the canister's principal as text, or remove canisterId`
+  }
+  if (isPrincipalText(canisterId)) return undefined
+  return (
+    `canisterId is ${describeValue(canisterId)}, not a canister ID: it is not the text of a principal, ` +
+    `which is lowercase, in groups of five joined by dashes, with a checksum, and at most 63 characters. ` +
+    `Give the canister's ID as it is printed, or remove canisterId`
+  )
+}
+
+/** A read of one option: its value, or what reading it threw. */
+type Read = { value: unknown; threw?: undefined } | { threw: string }
+
+/** Read `key` of `object`, once. Never throws. */
+function readKey(object: Record<string, unknown>, key: string): Read {
+  try {
+    return { value: object[key] }
+  } catch (error) {
+    return { threw: describeError(error) }
+  }
+}
+
+/**
+ * The keys of `object`, its own enumerable ones, or what listing them threw
+ * (a proxy's trap). Runs no getter. Never throws.
+ */
+function listKeys(
+  object: Record<string, unknown>
+): { keys: string[]; threw?: undefined } | { threw: string } {
+  try {
+    return { keys: Object.keys(object) }
+  } catch (error) {
+    return { threw: describeError(error) }
+  }
+}
+
+/** `a`, `a and b`, `a, b and c`. */
+function listAnd(items: readonly string[]): string {
+  return items.length < 2
+    ? items.join("")
+    : `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`
+}
+
+/**
+ * How many single letters must be added, removed or replaced to turn `a`
+ * into `b`.
+ */
+function editDistance(a: string, b: string): number {
+  let row = Array.from({ length: b.length + 1 }, (_, j) => j)
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i]
+    for (let j = 1; j <= b.length; j++) {
+      next.push(
+        Math.min(
+          row[j] + 1,
+          next[j - 1] + 1,
+          row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+        )
+      )
+    }
+    row = next
+  }
+  return row[b.length]
+}
+
+/**
+ * The option of `options` that `key` may misspell: the nearest, case aside,
+ * within two letters (`canister`, `didfile`, `canisterID`); `undefined` when
+ * none is that near.
+ */
+function misspelt(key: string, options: readonly string[]): string | undefined {
+  let nearest: string | undefined
+  let distance = 3
+  for (const option of options) {
+    // More than two letters apart by their lengths alone.
+    if (Math.abs(key.length - option.length) >= distance) continue
+    const apart = editDistance(key.toLowerCase(), option.toLowerCase())
+    if (apart < distance) {
+      nearest = option
+      distance = apart
+    }
+  }
+  return nearest
+}
+
+/**
+ * Why `keys`, the keys of an object of options, are not all among its
+ * `options`, or `undefined` when they are: each key that is none, quoted as
+ * given, with the option it may misspell. A key is refused whatever its
+ * value, `undefined` included: the key is what is wrong, and a misspelled
+ * `canisterID: process.env.LEDGER_ID` is so whether the variable is set or
+ * not.
+ */
+function unknownKeysProblem(
+  keys: readonly string[],
+  options: readonly string[]
+): string | undefined {
+  const unknown = keys.filter((key) => !options.includes(key))
+  if (unknown.length === 0) return undefined
+  const quoted = unknown.map((key) => {
+    const meant = misspelt(key, options)
+    return meant === undefined
+      ? describeValue(key)
+      : `${describeValue(key)} (did you mean ${meant}?)`
+  })
+  return `${listAnd(quoted)} ${unknown.length === 1 ? "is not an option" : "are not options"}`
+}
+
+/**
+ * The plugin's options, read and checked. Throws an `Error` that says what to
+ * change for an option of the whole plugin that is not one, or a key of the
+ * options that is no option; a canister's options never throw, and refuse
+ * that canister instead.
+ */
+export function readOptions(given: unknown): ReadOptions {
+  const options = given === undefined ? {} : given
+  if (!isOptionsObject(options)) {
+    throw new Error(
+      `[ic-reactor] the options are ${describeNotPlain(options)}, not a plain object: give icReactor() an object of options, or none`
+    )
+  }
+  // Every key is an option: a misspelled `canister`, never read, would start
+  // the plugin with no canister, without a word.
+  const listed = listKeys(options)
+  if (listed.threw !== undefined) {
+    throw new Error(
+      `[ic-reactor] the options could not be listed: ${listed.threw}`
+    )
+  }
+  const unknown = unknownKeysProblem(listed.keys, PLUGIN_OPTIONS)
+  if (unknown !== undefined) {
+    throw new Error(
+      `[ic-reactor] ${unknown} of icReactor(): its options are ${listAnd(PLUGIN_OPTIONS)}`
+    )
+  }
+  const top = (key: string): unknown => {
+    const read = readKey(options, key)
+    if (read.threw !== undefined) {
+      throw new Error(
+        `[ic-reactor] the option ${key} could not be read: ${read.threw}`
+      )
+    }
+    return read.value
+  }
+  // Thrown, so that the config does not load: either value read by guess
+  // could ship stale bindings or drop the local environment.
+  const injectEnvironment = top("injectEnvironment")
+  const failOnError = top("failOnError")
+  const problem =
+    booleanProblem("injectEnvironment", injectEnvironment) ??
+    booleanProblem("failOnError", failOnError)
+  if (problem) throw new Error(problem)
+  // Thrown too: a hook that is not a function would fail every run, or, read
+  // by truthiness, be skipped without a word.
+  const onGenerated = top("onGenerated")
+  if (onGenerated !== undefined && typeof onGenerated !== "function") {
+    throw new Error(
+      `[ic-reactor] onGenerated is ${describeValue(onGenerated)}, not a function: ` +
+        `give it a function to call after each generated module, or remove it`
+    )
+  }
+
+  // Only an omitted `canisters` is none: `null` is refused below, as any other
+  // value that is not a plain object of canisters is, a `Map` or a `Promise`
+  // of them included.
+  const givenCanisters = top("canisters")
+  const canisters = givenCanisters === undefined ? {} : givenCanisters
+  if (!isOptionsObject(canisters)) {
+    throw new Error(
+      `[ic-reactor] canisters is ${describeNotPlain(canisters)}, not a plain object of canisters by name: ` +
+        `give each canister's options under its name, or remove canisters`
+    )
+  }
+  let keys: string[]
+  try {
+    keys = Object.keys(canisters)
+  } catch (error) {
+    throw new Error(
+      `[ic-reactor] the canisters could not be listed: ${describeError(error)}`
+    )
+  }
+
+  const read: ReadOptions = {
+    // Checked above: `undefined` or a boolean.
+    injectEnvironment:
+      injectEnvironment === undefined ? true : (injectEnvironment as boolean),
+    failOnError: failOnError as boolean | undefined,
+    // Checked above: `undefined` or a function.
+    onGenerated: onGenerated as IcReactorPluginOptions["onGenerated"],
+    names: [],
+    uncarriedNames: [],
+    configuredCanisterIds: new Map(),
+    notCanisterIds: [],
+    generated: [],
+    refused: [],
+  }
+  for (const name of keys) {
+    const entry = readKey(canisters, name)
+    // Omitted, as a conditional entry of a JavaScript config is.
+    if (entry.threw === undefined && entry.value === undefined) continue
+    // The cookie names every canister an entry names, but one whose name it
+    // cannot carry: read back, that one would be another key.
+    const carried = cookieCarries(name)
+    ;(carried ? read.names : read.uncarriedNames).push(name)
+    if (entry.threw !== undefined || !isOptionsObject(entry.value)) {
+      read.refused.push({
+        name,
+        problem:
+          entry.threw !== undefined
+            ? `its options could not be read: ${entry.threw}`
+            : `its options are ${describeNotPlain(entry.value)}, not a plain object of options (didFile, canisterId, …)`,
+        givesCanisterId: false,
+      })
+      continue
+    }
+    readCanister(name, entry.value, read, carried)
+  }
+  return read
+}
+
+/**
+ * Read and check the options of the canister `name`, into `read`. `carried`:
+ * whether the cookie carries its name, and so its `canisterId`.
+ */
+function readCanister(
+  name: string,
+  entry: Record<string, unknown>,
+  read: ReadOptions,
+  carried: boolean
+): void {
+  const problems: string[] = []
+  // Every key is an option, whatever its value: a misspelled `didfile`, never
+  // read, would take the canister for one only named in the cookie, and a
+  // misspelled `canisterID` would generate it without its ID.
+  const listed = listKeys(entry)
+  if (listed.threw !== undefined) {
+    problems.push(`its options could not be listed: ${listed.threw}`)
+  } else {
+    const unknown = unknownKeysProblem(listed.keys, CANISTER_OPTIONS)
+    if (unknown !== undefined) {
+      problems.push(
+        `${unknown} of a canister: its options are ${listAnd(CANISTER_OPTIONS)}`
+      )
+    }
+  }
+  /** The value of `key`, `undefined` with a problem when reading it threw. */
+  const value = (key: string): unknown => {
+    const result = readKey(entry, key)
+    if (result.threw === undefined) return result.value
+    problems.push(`${key} could not be read: ${result.threw}`)
+    return undefined
+  }
+
+  const problemsBefore = problems.length
+  const didFile = value("didFile")
+  const didFileThrew = problems.length > problemsBefore
+  // A canister with no `didFile` generates nothing, and is only named in the
+  // cookie. Its other options are checked all the same: a value that is not
+  // one refuses it too.
+  const hasDidFile = didFile !== undefined || didFileThrew
+  const canisterIdRead = readKey(entry, "canisterId")
+  const canisterId =
+    canisterIdRead.threw === undefined ? canisterIdRead.value : undefined
+  const canisterIdWrong =
+    canisterIdRead.threw === undefined
+      ? canisterIdProblem(canisterId)
+      : undefined
+
+  // The cookie's: a configured ID wins over the one `icp` reports. Only a
+  // principal's text can be one: any other value given is left to `icp`, with
+  // a warning, rather than put in the cookie or taken for no canisterId. A
+  // canister the cookie cannot carry is in neither, and has the warning of
+  // its name; its `canisterId` is checked below all the same.
+  if (carried) {
+    if (canisterIdRead.threw !== undefined) {
+      read.notCanisterIds.push(
+        `${name}: could not be read (${canisterIdRead.threw})`
+      )
+    } else if (canisterId !== undefined && canisterIdWrong === undefined) {
+      read.configuredCanisterIds.set(name, canisterId as string)
+    } else if (canisterId !== undefined) {
+      read.notCanisterIds.push(`${name}: ${describeValue(canisterId)}`)
+    }
+  }
+
+  if (didFile !== undefined && !isPath(didFile)) {
+    problems.push(
+      `didFile is ${describeValue(didFile)}, not a path: give the canister's .did file relative to the Vite root, ` +
+        `or remove didFile for a canister that is only named in the ic_env cookie`
+    )
+  }
+  const outDir = value("outDir")
+  if (outDir !== undefined && !isPath(outDir)) {
+    problems.push(
+      `outDir is ${describeValue(outDir)}, not a path: give the directory relative to the Vite root, ` +
+        `or remove outDir for "src/canisters"`
+    )
+  }
+  if (canisterIdRead.threw !== undefined) {
+    problems.push(`canisterId could not be read: ${canisterIdRead.threw}`)
+  } else if (canisterIdWrong !== undefined) {
+    problems.push(canisterIdWrong)
+  }
+
+  // A copy: `{ host }` read once, so that no getter of the object given runs
+  // again when the network is resolved. Any other object (a `URL`, a `Map`,
+  // a `Promise`, a list) is not a network, whatever its `host`, and `{ host }`
+  // holds no other key: the plugin takes the root key from the host, so a
+  // `rootKey` or `fetchRootKey` would be read as nothing.
+  const givenNetwork = value("network")
+  let network: CanisterNetwork | undefined
+  if (isOptionsObject(givenNetwork)) {
+    const networkKeys = listKeys(givenNetwork)
+    if (networkKeys.threw !== undefined) {
+      problems.push(`network's keys could not be listed: ${networkKeys.threw}`)
+    } else {
+      const unknown = unknownKeysProblem(networkKeys.keys, NETWORK_OPTIONS)
+      if (unknown !== undefined) {
+        problems.push(
+          `${unknown} of network { host }: give the network as { host: "<http or https URL>" } alone`
+        )
+      }
+    }
+    const host = readKey(givenNetwork, "host")
+    if (host.threw !== undefined) {
+      problems.push(`network.host could not be read: ${host.threw}`)
+    } else {
+      network = { host: host.value } as CanisterNetwork
+    }
+  } else if (typeof givenNetwork === "object" && givenNetwork !== null) {
+    problems.push(
+      `network ${describeNotPlain(givenNetwork)} is not "ic", "local" or a plain object { host: "<http or https URL>" }`
+    )
+  } else {
+    network = givenNetwork as CanisterNetwork | undefined
+  }
+  if (network !== undefined) {
+    const resolved = resolveNetwork(network)
+    if (typeof resolved === "string") problems.push(resolved)
+  }
+
+  // A copy of the list, read once.
+  let methods = value("methods")
+  try {
+    if (Array.isArray(methods)) methods = Array.from(methods as unknown[])
+  } catch (error) {
+    problems.push(`methods could not be read: ${describeError(error)}`)
+    methods = undefined
+  }
+  const methodsWrong = methodsProblem(methods)
+  if (methodsWrong) problems.push(methodsWrong)
+
+  const verify = value("verify")
+  const verifyWrong = verifyProblem(verify)
+  if (verifyWrong) {
+    problems.push(verifyWrong)
+  } else if (verify === "live" && hasDidFile && canisterId === undefined) {
+    // With no `didFile`, there is nothing to check: `"live"` is a value, and
+    // unused.
+    if (canisterIdRead.threw === undefined) {
+      problems.push(
+        `verify is "live", but it names no canisterId to check its didFile against`
+      )
+    }
+  }
+
+  if (problems.length > 0) {
+    read.refused.push({
+      name,
+      problem: problems.join("; "),
+      didFile: isPath(didFile) ? didFile : undefined,
+      givesCanisterId: canisterId !== undefined || !!canisterIdRead.threw,
+    })
+    return
+  }
+  if (!hasDidFile) return
+  read.generated.push({
+    name,
+    didFile: didFile as string,
+    // Checked above: `undefined` or a path.
+    outDir: outDir === undefined ? DEFAULT_OUT_DIR : (outDir as string),
+    canisterId: canisterId as string | undefined,
+    network,
+    methods: methods as readonly string[] | undefined,
+    verify: verify as "live" | undefined,
+  })
+}