lecodes-cli 0.20.2 → 2.0.0

package/src/plugin/emitSwift.ts

@@ -0,0 +1,336 @@
+// The generator's emitter for `ios/`: a contract's channel → `<Name>.gen.swift`, everything of the
+// iOS half that is not the plugin's own work (docs/plans/plugins-plan.md in core):
+//   - the contract's types as Swift (enums, structs, tagged unions) with their wire codecs;
+//   - `<Name>Code`: the codes the channel rejects with;
+//   - `<Name>Events`: one function per event;
+//   - `<Name>Plugin`: the PROTOCOL the plugin implements — one method per call, a typed `Reply`;
+//   - `<Name>Channel.register(in:_:)` + the glue that reads a call's arguments, refuses a malformed
+//     one and hands the call over.
+// It stands on the host SDK's PluginChannel.swift (Reply, PluginFile) and on the wire's two ends
+// (WireIn, WireOut). The wire carries VALUES, and the codecs read a struct straight out of the
+// runtime's value and write one straight into it — no tree of Foundation's objects in between. A
+// Uint8Array is a `Data`, a File the handle of a host buffer; a `Json` member alone is Foundation's
+// objects, because JSON is what a half does with it.
+
+import { EmitError } from "./emitSdk"
+import { block, indent, text, wrap, writerName } from "./lines"
+import { waysOf, type L, type LChannel, type LDecl, type LField, type Lowered, type Ways } from "./lower"
+
+const KEYWORDS = new Set([
+  "associatedtype", "class", "deinit", "enum", "extension", "fileprivate", "func", "import", "init", "inout", "internal",
+  "let", "open", "operator", "private", "protocol", "public", "rethrows", "static", "struct", "subscript", "typealias",
+  "var", "break", "case", "continue", "default", "defer", "do", "else", "fallthrough", "for", "guard", "if", "in",
+  "repeat", "return", "switch", "where", "while", "as", "catch", "false", "is", "nil", "super", "self", "Self", "throw",
+  "throws", "true", "try", "Any", "Type", "Protocol",
+])
+
+const ident = (name: string): string => KEYWORDS.has(name) ? `\`${name}\`` : name
+
+/** A string of the contract as a Swift case: `"not-asked"` → `notAsked`. */
+const caseName = (value: string): string => {
+  const words = value.split(/[^A-Za-z0-9]+/).filter(Boolean)
+  const name = words.map((w, i) => i === 0 ? w.charAt(0).toLowerCase() + w.slice(1) : w.charAt(0).toUpperCase() + w.slice(1)).join("")
+  return /^[A-Za-z_]/.test(name) ? name : `_${name}`
+}
+
+const lowerFirst = (s: string): string => s.charAt(0).toLowerCase() + s.slice(1)
+
+const doc = (text: string, indent = ""): string =>
+  text ? text.split("\n").map(l => `${indent}/// ${l.trim()}`.trimEnd()).join("\n") + "\n" : ""
+
+export const swiftType = (t: L): string => {
+  switch (t.kind) {
+    case "i32": return "Int32"
+    case "f64": return "Double"
+    case "boolean": return "Bool"
+    case "string": return "String"
+    case "json": return "Any"
+    case "file": return "PluginFile"
+    case "bytes": return "Data"
+    case "void": return "Void"
+    case "enum": case "struct": case "union": return t.name
+    case "list": return `[${swiftType(t.of)}]`
+    case "map": return `[String: ${swiftType(t.of)}]`
+    case "optional": return `${swiftType(t.of)}?`
+    case "tuple": return `(${t.of.map(swiftType).join(", ")})`
+  }
+}
+
+/** The expression of type `T?` that reads the wire's value `e` (a `WireIn`), as lines: nil = it is
+ *  not a T. */
+const decode = (t: L, e: string, depth = 0): string[] => {
+  const v = `v${depth}`
+  switch (t.kind) {
+    case "i32": return [`${e}.i32`]
+    case "f64": return [`${e}.f64`]
+    case "boolean": return [`${e}.bool`]
+    case "string": return [`${e}.string`]
+    case "json": return [`${e}.json`]
+    case "bytes": return [`${e}.bytes`]
+    case "file": return [`${e}.file`]
+    case "enum": case "struct": case "union": return [`${t.name}(wire: ${e})`]
+    // Closures are ARGUMENTS, never trailing: a trailing one does not parse inside a `guard` condition.
+    case "list": return block(`${e}.list({ ${v} in`, decode(t.of, v, depth + 1), `})`)
+    case "map": return block(`${e}.map({ ${v} in`, decode(t.of, v, depth + 1), `})`)
+    case "optional": return decode(t.of, e, depth)
+    case "tuple": {
+      const parts = t.of.map((m, i) => ({ name: `${v}_${i}`, lines: decode(m, `${v}[${i}]`, depth + 1) }))
+      // Scalars are read in one `guard`; a member of several lines has one of its own.
+      const guards = parts.every(p => p.lines.length === 1)
+        ? [`guard ${parts.map(p => `let ${p.name} = ${p.lines[0]}`).join(", ")} else { return nil }`]
+        : parts.flatMap(p => wrap(`guard let ${p.name} = `, p.lines, ` else { return nil }`))
+      return [
+        `${e}.tuple(${t.of.length}).flatMap({ ${v} -> ${swiftType(t)}? in`,
+        ...indent([...guards, `return (${parts.map(p => p.name).join(", ")})`]),
+        `})`,
+      ]
+    }
+    case "void": throw new EmitError("void has no value to read")
+  }
+}
+
+/** The statements that write the value `e` (a `T`) to the wire `w` (a `WireOut`), as lines. */
+const encode = (t: L, e: string, w: string, depth = 0): string[] => {
+  const v = `v${depth}`
+  switch (t.kind) {
+    case "i32": return [`${w}.i32(${e})`]
+    case "f64": return [`${w}.f64(${e})`]
+    case "boolean": return [`${w}.bool(${e})`]
+    case "string": return [`${w}.string(${e})`]
+    case "json": return [`${w}.json(${e})`]
+    case "bytes": return [`${w}.bytes(${e})`]
+    case "enum": return [`${w}.string(${e}.rawValue)`]
+    case "file": case "struct": case "union": return [`${e}.write(to: ${w})`]
+    case "list": return [`${w}.beginArray(${e}.count)`, ...block(`for ${v} in ${e} {`, encode(t.of, v, w, depth + 1), `}`), `${w}.end()`]
+    case "map": return [`${w}.beginObject(${e}.count)`, `for (k${depth}, ${v}) in ${e} {`, ...indent([`${w}.name(k${depth})`, ...encode(t.of, v, w, depth + 1)]), `}`, `${w}.end()`]
+    case "tuple": return [`${w}.beginArray(${t.of.length})`, ...t.of.flatMap((m, i) => encode(m, `${e}.${i}`, w, depth + 1)), `${w}.end()`]
+    case "optional": {
+      const some = encode(t.of, v, w, depth + 1)
+      const one = `if let ${v} = ${e} { ${some[0]} } else { ${w}.null() }`
+      return some.length === 1 && one.length <= 100 ? [one] : [`if let ${v} = ${e} {`, ...indent(some), `} else {`, ...indent([`${w}.null()`]), `}`]
+    }
+    case "void": throw new EmitError("void has no value to write")
+  }
+}
+
+/** A value under its key: on the key's line when it is one plain statement. */
+const keyed = (key: string, value: string[]): string[] =>
+  value.length === 1 && !/^(if|for) /.test(value[0]!) ? [`${key}; ${value[0]}`] : [key, ...value]
+
+/** The statements that write a struct's members — an object — to the wire `w`, as lines. */
+const encodeFields = (fields: LField[], of: (f: LField) => string, w: string): string[] => [
+  `${w}.beginObject(${fields.length})`,
+  ...fields.flatMap(f => {
+    const key = `${w}.key(${JSON.stringify(f.name)})`
+    if (f.type.kind !== "optional") return keyed(key, encode(f.type, of(f), w))
+    // An optional member that is nil is left out; a nullable one is written as a null.
+    if (f.omit) return block(`if let v = ${of(f)} {`, keyed(key, encode(f.type.of, "v", w, 1)), `}`)
+    return keyed(key, encode(f.type, of(f), w))
+  }),
+  `${w}.end()`,
+]
+
+const unionCase = (m: L): string => {
+  switch (m.kind) {
+    case "f64": return "number"
+    case "i32": return "integer"
+    case "boolean": return "bool"
+    case "string": return "string"
+    case "enum": case "struct": return lowerFirst(m.name)
+    default: return m.kind
+  }
+}
+
+const emitDecl = (d: LDecl, ways: Ways): string => {
+  const read = ways.read.has(d.name)
+  const write = ways.write.has(d.name)
+  if (d.kind === "enum") {
+    const cases = d.values.map(v => {
+      const name = caseName(v)
+      return `    case ${ident(name)}${name === v ? "" : ` = ${JSON.stringify(v)}`}`
+    })
+    return [
+      doc(d.doc),
+      `public enum ${d.name}: String {\n${cases.join("\n")}\n`,
+      read ? `\n    init?(wire: WireIn) {\n        guard let raw = wire.string, let value = ${d.name}(rawValue: raw) else { return nil }\n        self = value\n    }\n` : "",
+      `}\n`,
+    ].join("")
+  }
+
+  if (d.kind === "union") {
+    const cases = d.members.map(m => `    case ${ident(unionCase(m))}(${swiftType(m)})`)
+    const reads = !read ? [] : d.members.flatMap(m => [
+      ...wrap(`if let v = `, decode(m, "wire", 1), ` {`),
+      ...indent([`self = .${ident(unionCase(m))}(v)`, `return`]),
+      `}`,
+    ])
+    const writes = !write ? [] : d.members.flatMap(m => {
+      const lines = encode(m, "v", "w", 1)
+      const head = `case .${ident(unionCase(m))}(let v):`
+      return lines.length === 1 ? [`${head} ${lines[0]}`] : [head, ...indent(lines)]
+    })
+    return [
+      doc(d.doc),
+      `public enum ${d.name} {\n${cases.join("\n")}\n`,
+      read ? `\n    init?(wire: WireIn) {\n${text(reads, "        ")}\n        return nil\n    }\n` : "",
+      write ? `\n    func write(to w: WireOut) {\n        switch self {\n${text(writes, "        ")}\n        }\n    }\n` : "",
+      `}\n`,
+    ].join("")
+  }
+
+  const members = d.fields.map(f => `${doc(f.doc, "    ")}    public var ${ident(f.name)}: ${swiftType(f.type)}`)
+  const initArgs = d.fields.map(f => `${ident(f.name)}: ${swiftType(f.type)}${f.type.kind === "optional" ? " = nil" : ""}`)
+  const initBody = d.fields.map(f => `        self.${ident(f.name)} = ${ident(f.name)}`)
+  // The members are read into numbered locals and written from `self.`: a member's own name is
+  // never an identifier here, so none can shadow the wire.
+  const reads = !read ? [] : d.fields.flatMap((f, i) => {
+    const at = `wire[${JSON.stringify(f.name)}, ${i}]`
+    const name = ident(f.name)
+    if (f.type.kind !== "optional") return [...wrap(`guard let m${i} = `, decode(f.type, at), ` else { return nil }`), `self.${name} = m${i}`]
+    // An optional member that IS there must read: a wrong type is a malformed value, not an absent one.
+    return [
+      `let m${i} = ${at}`,
+      `if m${i}.isPresent {`,
+      ...indent([...wrap(`guard let v = `, decode(f.type, `m${i}`), ` else { return nil }`), `self.${name} = v`]),
+      `} else {`,
+      ...indent([`self.${name} = nil`]),
+      `}`,
+    ]
+  })
+  return [
+    doc(d.doc),
+    `public struct ${d.name} {\n`,
+    members.length ? members.join("\n") + "\n\n" : "",
+    `    public init(${initArgs.join(", ")}) {${initBody.length ? "\n" + initBody.join("\n") + "\n    " : ""}}\n`,
+    !read ? "" : d.fields.length
+      ? `\n    init?(wire: WireIn) {\n        guard wire.isObject else { return nil }\n${text(reads, "        ")}\n    }\n`
+      : `\n    init?(wire: WireIn) {\n        guard !wire.isPresent || wire.isObject else { return nil }\n    }\n`,
+    !write ? "" : `\n    func write(to w: WireOut) {\n${text(encodeFields(d.fields, f => `self.${ident(f.name)}`, "w"), "        ")}\n    }\n`,
+    `}\n`,
+  ].join("")
+}
+
+const emitChannel = (ch: LChannel): string => {
+  const isView = ch.kind === "view"
+  const iface = ch.iface
+  const code = ch.codes.length ? `${iface}Code` : "NoCode"
+  const out: string[] = []
+
+  if (ch.codes.length) {
+    out.push(`/// The codes the calls of "${ch.name}" reject with.\npublic enum ${iface}Code: String, PluginCode {\n${ch.codes.map(c => `    case ${ident(c)}`).join("\n")}\n}\n`)
+  }
+
+  // ---- events ----
+  const events = ch.events.map(e => {
+    const name = ident(e.name)
+    if (e.inline) {
+      const args = e.inline.map(f => `${ident(f.name)}: ${swiftType(f.type)}${f.type.kind === "optional" ? " = nil" : ""}`)
+      const w = writerName(e.inline.map(f => f.name))
+      return `${doc(e.doc, "    ")}    public func ${name}(${args.join(", ")}) {\n        self.channel.emit(${JSON.stringify(e.name)}) { ${w} in\n${text(encodeFields(e.inline, f => ident(f.name), w), "            ")}\n        }\n    }`
+    }
+    if (e.payload.kind === "void") return `${doc(e.doc, "    ")}    public func ${name}() { channel.emit(${JSON.stringify(e.name)}) }`
+    const emit = block(`channel.emit(${JSON.stringify(e.name)}) { w in`, encode(e.payload, "payload", "w"), `}`)
+    return `${doc(e.doc, "    ")}    public func ${name}(_ payload: ${swiftType(e.payload)}) {\n${text(emit, "        ")}\n    }`
+  })
+  out.push([
+    `/// The events of "${ch.name}": what the plugin sends the app. Any thread.\n`,
+    `public struct ${iface}Events {\n    let channel: ${isView ? "NativeViewChannel" : "ServiceChannel"}\n`,
+    events.length ? "\n" + events.join("\n\n") + "\n" : "",
+    `}\n`,
+  ].join(""))
+
+  // ---- the protocol ----
+  const signatures = ch.methods.map(m => {
+    const args = [...m.args.map(a => `_ ${ident(a.name)}: ${swiftType(a.type)}`), `_ reply: Reply<${swiftType(m.result)}, ${code}>`]
+    const tags = [m.doc, m.rejects.length ? `Rejects with ${m.rejects.map(r => `.${r}`).join(" / ")}.` : ""].filter(Boolean).join("\n")
+    return `${doc(tags, "    ")}    func ${ident(m.name)}(${args.join(", ")})`
+  })
+  out.push([
+    doc(ch.doc || `The ${ch.kind} "${ch.name}".`),
+    `/// What the plugin implements. A call arrives on the main thread; its reply is settled exactly\n/// once, now or later, from any thread.\n`,
+    `public protocol ${iface}Plugin: AnyObject {\n`,
+    isView ? `    /// The view the host mounts: fullscreen, or embedded among a screen's children.\n    var view: UIView { get }\n` : "",
+    signatures.length ? (isView ? "\n" : "") + signatures.join("\n") + "\n" : "",
+    isView
+      ? `\n    /// The instance goes (the world swapped): release the hardware.\n    func destroy()\n`
+      : `\n    /// The session closed (the app's close, the world's teardown): stop what it started.\n    func close()\n`,
+    `}\n\npublic extension ${iface}Plugin {\n    func ${isView ? "destroy" : "close"}() {}\n}\n`,
+  ].join(""))
+
+  // ---- registration ----
+  out.push([
+    `public enum ${iface}Channel {\n`,
+    `    /// What the halves register under.\n    public static let name = ${JSON.stringify(ch.name)}\n`,
+    `    /// The contract's version: the highest \`@since\` of its members.\n    public static let version = ${ch.version}\n\n`,
+    `    /// Register the ${ch.kind}: \`make\` builds ${isView ? "one instance" : "one session"} from its params. ${isView ? "" : "It must be cheap — no prompt,\n    /// no I/O: that belongs to the first call that needs it."}\n`.replace(/ \n/, "\n"),
+    `    public static func register(in engine: LeCodesEngine, _ make: @escaping (${ch.params}, ${iface}Events) -> ${iface}Plugin) {\n`,
+    `        engine.register${isView ? "View" : "Service"}(name, version: Int32(version)) { params, channel in\n`,
+    `            ${iface}Glue(make(WireIn.of(params, { ${ch.params}(wire: $0) }) ?? ${ch.params}(), ${iface}Events(channel: channel)))\n`,
+    `        }\n    }\n}\n`,
+  ].join(""))
+
+  // ---- the glue ----
+  // The arguments are read into numbered locals: an argument's own name is never an identifier here.
+  const cases = ch.methods.map(m => {
+    const lines: string[] = []
+    m.args.forEach((a, i) => {
+      const bad = `return settle.reject("bad arguments — ${iface}.${m.name}: ${a.name}")`
+      if (a.type.kind !== "optional") {
+        lines.push(...wrap(`guard let a${i} = `, decode(a.type, `args[${i}]`), ` else { ${bad} }`))
+      } else {
+        lines.push(
+          `let w${i} = args[${i}]`,
+          `var a${i}: ${swiftType(a.type)} = nil`,
+          `if w${i}.isPresent {`,
+          ...indent([...wrap(`guard let v = `, decode(a.type, `w${i}`), ` else { ${bad} }`), `a${i} = v`]),
+          `}`,
+        )
+      }
+    })
+    const head = `Reply<${swiftType(m.result)}, ${code}>(settle)`
+    const reply = m.result.kind === "void"
+      ? [head]
+      : m.result.kind === "optional"
+        // Nothing is written for nil: the app's promise resolves with `undefined`.
+        ? block(`${head} { v, w in`, block(`if let v1 = v {`, encode(m.result.of, "v1", "w", 2), `}`), `}`)
+        : block(`${head} { v, w in`, encode(m.result, "v", "w", 1), `}`)
+    lines.push(...wrap(`plugin.${ident(m.name)}(${m.args.map((_, i) => `a${i}, `).join("")}`, reply, `)`))
+    return `        case ${JSON.stringify(m.name)}:\n${text(lines, "            ")}`
+  })
+  out.push([
+    `/// Reads a call off the wire and hands it to the plugin; a malformed call never reaches it.\n`,
+    `final class ${iface}Glue: ${isView ? "WireNativeViewInstance" : "WireServiceInstance"} {\n`,
+    `    private let plugin: ${iface}Plugin\n\n`,
+    `    init(_ plugin: ${iface}Plugin) { self.plugin = plugin }\n\n`,
+    isView ? `    var view: UIView { plugin.view }\n\n` : "",
+    `    func call(_ method: String, wire args: WireIn, _ settle: ChannelSettle) {\n        switch method {\n`,
+    cases.length ? cases.join("\n") + "\n" : "",
+    `        default:\n            settle.reject("Unknown method: \\(method)")\n        }\n    }\n\n`,
+    `    func ${isView ? "destroy" : "close"}() { plugin.${isView ? "destroy" : "close"}() }\n}\n`,
+  ].join(""))
+
+  return out.join("\n")
+}
+
+export type SwiftEmitOptions = { id: string }
+
+/** One file per plugin: the types every channel of the contract reaches, then each channel. */
+export const emitSwift = (lowered: Lowered, opts: SwiftEmitOptions): string => {
+  const views = lowered.channels.some(c => c.kind === "view")
+  const header = lowered.channels.map(c => `the ${c.kind} "${c.name}", contract version ${c.version}`).join("; ")
+  const guarded = (what: string, body: () => string): string => {
+    try { return body() } catch (e) {
+      if (e instanceof EmitError) throw new EmitError(`${what}: ${e.message}`)
+      throw e
+    }
+  }
+  const ways = waysOf(lowered)
+  return [
+    `// GENERATED by \`lecodes plugin gen\` from contract.d.ts — do not edit.\n`,
+    `// ${opts.id}: ${header}.\n\n`,
+    `import Foundation\n${views ? "import UIKit\n" : ""}import LeCodes\n\n`,
+    `// MARK: - The contract's types\n\n`,
+    lowered.decls.map(d => guarded(d.name, () => emitDecl(d, ways))).join("\n"),
+    ...lowered.channels.map(ch => `\n// MARK: - ${ch.iface}\n\n${guarded(ch.iface, () => emitChannel(ch))}`),
+  ].join("")
+}