lecodes-cli 0.20.2 → 2.0.0

package/src/plugin/emitWeb.ts

@@ -0,0 +1,383 @@
+// The generator's emitter for `web/`: a contract → `<id>.gen.ts`, everything of the web half that is
+// not the plugin's own work (docs/plans/plugins-plan.md in core) — the twin of emitSwift.ts and
+// emitKotlin.ts, over the same lowered model:
+//   - the contract's types, as the half reads and writes them;
+//   - `<Name>Code` + `<Name>Error`: the codes the channel rejects with, thrown;
+//   - `<Name>Events`: one function per event;
+//   - `<Name>Plugin`: the INTERFACE the half implements — one method per call, a value or a promise;
+//   - `register<Name>(host, make)` + the glue that reads a call's arguments, refuses a malformed one
+//     and hands the call over.
+//
+// The wire carries VALUES, and on the web the app's own: a Uint8Array crosses as it is, a File as the
+// handle of a host buffer.
+//
+// The file imports NOTHING. A web half depends on its generated file, on the document it is handed
+// and on the browser — which is what lets another host (web-lite) and a prebuilt third-party module
+// take the same half. What the host is asked for is a SHAPE (`PluginHost`), declared in the file.
+
+import { EmitError } from "./emitSdk"
+import { waysOf, type L, type LChannel, type LDecl, type LField, type Lowered, type Ways } from "./lower"
+
+const str = (value: string): string => JSON.stringify(value)
+const key = (name: string): string => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : str(name)
+const at = (o: string, name: string): string => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? `${o}.${name}` : `${o}[${str(name)}]`
+
+const doc = (text: string, indent = ""): string => {
+  if (!text) return ""
+  const lines = text.split("\n").map(l => l.trim())
+  if (lines.length === 1) return `${indent}/** ${lines[0]} */\n`
+  return `${indent}/** ${lines[0]}\n${lines.slice(1).map(l => `${indent} *  ${l}`.trimEnd()).join("\n")} */\n`
+}
+
+/** A type as the half names it. An optional that is not a member's or an argument's is a null. */
+export const webType = (t: L): string => {
+  switch (t.kind) {
+    case "i32": case "f64": return "number"
+    case "boolean": return "boolean"
+    case "string": return "string"
+    case "json": return "Json"
+    case "file": return "PluginFile"
+    case "bytes": return "Uint8Array"
+    case "void": return "void"
+    case "enum": case "struct": case "union": return t.name
+    case "list": return `${t.of.kind === "optional" ? `(${webType(t.of)})` : webType(t.of)}[]`
+    case "map": return `{ [key: string]: ${webType(t.of)} }`
+    case "optional": return `${webType(t.of)} | null`
+    case "tuple": return `[${t.of.map(webType).join(", ")}]`
+  }
+}
+
+/** A member or an argument: left out (`name?: T`) or null (`name: T | null`). */
+const member = (name: string, type: L, omit: boolean): string =>
+  type.kind === "optional" && omit ? `${key(name)}?: ${webType(type.of)}` : `${key(name)}: ${webType(type)}`
+
+/** The expression of type `T | undefined` that reads the wire's value `e`: undefined = it is not a T. */
+const decode = (t: L, e: string, depth = 0): string => {
+  const v = `v${depth}`
+  switch (t.kind) {
+    case "i32": return `wire.i32(${e})`
+    case "f64": return `wire.f64(${e})`
+    case "boolean": return `wire.bool(${e})`
+    case "string": return `wire.string(${e})`
+    case "json": return `wire.json(${e})`
+    case "bytes": return `wire.bytes(${e})`
+    case "file": return `readFile(${e})`
+    case "enum": case "struct": case "union": return `read${t.name}(${e})`
+    case "list": return `wire.list(${e}, (${v}) => ${decode(t.of, v, depth + 1)})`
+    case "map": return `wire.map(${e}, (${v}) => ${decode(t.of, v, depth + 1)})`
+    // Absent and null are one thing on the wire: a null here.
+    case "optional": return `(wire.present(${e}) ? ${decode(t.of, e, depth)} : null)`
+    case "tuple": {
+      const parts = t.of.map((m, i) => `const ${v}_${i} = ${decode(m, `${v}[${i}]`, depth + 1)}; if (${v}_${i} === undefined) return undefined`)
+      return `((${v}): ${webType(t)} | undefined => { if (!${v}) return undefined; ${parts.join("; ")}; return [${t.of.map((_, i) => `${v}_${i}`).join(", ")}] })(wire.array(${e}, ${t.of.length}))`
+    }
+    case "void": throw new EmitError("void has no value to read")
+  }
+}
+
+export type WebEmitOptions = { id: string }
+
+export const emitWeb = (lowered: Lowered, opts: WebEmitOptions): string => {
+  const byName = new Map(lowered.decls.map(d => [d.name, d]))
+  const ways: Ways = waysOf(lowered)
+
+  /** Does a value of this type hold a File anywhere? Only such a value is rewritten on its way out:
+   *  everything else — a Uint8Array too — leaves as the half made it, and the app gets that value. */
+  const carriesFile = (t: L, seen = new Set<string>()): boolean => {
+    switch (t.kind) {
+      case "file": return true
+      case "list": case "map": case "optional": return carriesFile(t.of, seen)
+      case "tuple": return t.of.some(m => carriesFile(m, seen))
+      case "struct": case "union": {
+        if (seen.has(t.name)) return false
+        seen.add(t.name)
+        const d = byName.get(t.name)!
+        if (d.kind === "struct") return d.fields.some(f => carriesFile(f.type, seen))
+        if (d.kind === "union") return d.members.some(m => carriesFile(m, seen))
+        return false
+      }
+      default: return false
+    }
+  }
+
+  /** The expression that writes the value `e` to the wire. */
+  const encode = (t: L, e: string, depth = 0): string => {
+    if (!carriesFile(t)) return e
+    const v = `v${depth}`
+    switch (t.kind) {
+      case "file": return `writeFile(host, ${e})`
+      case "struct": return `write${t.name}(host, ${e})`
+      case "list": return `${e}.map((${v}) => ${encode(t.of, v, depth + 1)})`
+      case "map": return `Object.fromEntries(Object.entries(${e}).map(([k, ${v}]) => [k, ${encode(t.of, v, depth + 1)}]))`
+      case "tuple": return `[${t.of.map((m, i) => encode(m, `${e}[${i}]`, depth + 1)).join(", ")}]`
+      case "optional": return `(${e} == null ? null : ${encode(t.of, e, depth)})`
+      // A union is told apart by what its members are on the wire; a File among them is not a thing
+      // the lowering lets through.
+      default: throw new EmitError(`a File inside a ${t.kind} is not written by this generator`)
+    }
+  }
+
+  const emitDecl = (d: LDecl): string => {
+    const read = ways.read.has(d.name)
+    const write = ways.write.has(d.name) && carriesFile({ kind: d.kind, name: d.name } as L)
+    if (d.kind === "enum") {
+      const values = d.values.map(str)
+      return [
+        doc(d.doc),
+        `export type ${d.name} = ${values.join(" | ")}\n`,
+        read ? `const read${d.name} = (v: unknown): ${d.name} | undefined =>\n  ${values.map(x => `v === ${x}`).join(" || ")} ? v : undefined\n` : "",
+      ].join("")
+    }
+    if (d.kind === "union") {
+      return [
+        doc(d.doc),
+        `export type ${d.name} = ${d.members.map(webType).join(" | ")}\n`,
+        read ? `const read${d.name} = (v: unknown): ${d.name} | undefined =>\n  ${d.members.map(m => decode(m, "v", 1)).join(" ?? ")}\n` : "",
+      ].join("")
+    }
+
+    const members = d.fields.map(f => `${doc(f.doc, "  ")}  ${member(f.name, f.type, f.omit)}`)
+    const reads = !read ? [] : d.fields.map((f, i) => {
+      const from = at("o", f.name)
+      if (f.type.kind !== "optional") return `  const f${i} = ${decode(f.type, from)}\n  if (f${i} === undefined) return undefined`
+      // An optional member that IS there must read: a wrong type is a malformed value, not an absent one.
+      const inner = decode(f.type.of, from)
+      return `  let f${i}: ${webType(f.type.of)} | ${f.omit ? "undefined" : "null"} = ${f.omit ? "undefined" : "null"}\n  if (wire.present(${from})) {\n    const r = ${inner}\n    if (r === undefined) return undefined\n    f${i} = r\n  }`
+    })
+    const required = d.fields.map((f, i) => ({ f, i })).filter(({ f }) => !(f.type.kind === "optional" && f.omit))
+    const left = d.fields.map((f, i) => ({ f, i })).filter(({ f }) => f.type.kind === "optional" && f.omit)
+    const reader = !read ? "" : d.fields.length === 0
+      ? `const read${d.name} = (v: unknown): ${d.name} | undefined => !wire.present(v) || wire.object(v) ? {} : undefined\n`
+      : [
+        `const read${d.name} = (v: unknown): ${d.name} | undefined => {\n  const o = wire.object(v)\n  if (!o) return undefined\n`,
+        reads.join("\n") + "\n",
+        `  const out: ${d.name} = ${required.length ? `{ ${required.map(({ f, i }) => `${key(f.name)}: f${i}`).join(", ")} }` : "{}"}\n`,
+        left.map(({ f, i }) => `  if (f${i} !== undefined) ${at("out", f.name)} = f${i}\n`).join(""),
+        `  return out\n}\n`,
+      ].join("")
+    const writer = !write ? "" : [
+      `const write${d.name} = (host: PluginHost, v: ${d.name}): unknown => ({\n  ...v,\n`,
+      d.fields.filter(f => carriesFile(f.type)).map(f => {
+        const from = at("v", f.name)
+        return f.type.kind === "optional" && f.omit
+          ? `  ...(${from} === undefined ? {} : { ${key(f.name)}: ${encode(f.type.of, from)} }),\n`
+          : `  ${key(f.name)}: ${encode(f.type, from)},\n`
+      }).join(""),
+      `})\n`,
+    ].join("")
+    return [
+      doc(d.doc),
+      `export interface ${d.name} {${members.length ? "\n" + members.join("\n") + "\n" : ""}}\n`,
+      reader, writer,
+    ].join("")
+  }
+
+  const emitChannel = (ch: LChannel): string => {
+    const isView = ch.kind === "view"
+    const iface = ch.iface
+    const out: string[] = []
+
+    if (ch.codes.length) {
+      out.push([
+        `/** The codes the calls of "${ch.name}" reject with. */\n`,
+        `export type ${iface}Code = ${ch.codes.map(str).join(" | ")}\n\n`,
+        `/** What a call throws to reject with a code of the contract — the app's promise rejects with it\n *  as the message. Any other error is a message the contract has no code for. */\n`,
+        `export class ${iface}Error extends Error {\n  constructor(readonly code: ${iface}Code) { super(code) }\n}\n`,
+      ].join(""))
+    }
+
+    // ---- events ----
+    const payloadOf = (e: LChannel["events"][number]): string | null =>
+      e.inline ? `{ ${e.inline.map(f => member(f.name, f.type, f.omit)).join(", ")} }` : e.payload.kind === "void" ? null : webType(e.payload)
+    const events = ch.events.map(e => {
+      const payload = payloadOf(e)
+      return `${doc(e.doc, "  ")}  ${key(e.name)}(${payload === null ? "" : `payload: ${payload}`}): void`
+    })
+    out.push(`/** The events of "${ch.name}": what the half sends the app. */\nexport interface ${iface}Events {${events.length ? "\n" + events.join("\n") + "\n" : ""}}\n`)
+
+    // ---- the interface ----
+    const signatures = ch.methods.map(m => {
+      const args = m.args.map(a => member(a.name, a.type, a.omit))
+      const result = webType(m.result)
+      const tags = [m.doc, m.rejects.length ? `Rejects with ${m.rejects.map(str).join(" / ")}.` : ""].filter(Boolean).join("\n")
+      return `${doc(tags, "  ")}  ${m.name}(${args.join(", ")}): ${result} | Promise<${result}>`
+    })
+    out.push([
+      doc(ch.doc || `The ${ch.kind} "${ch.name}".`).replace(/ \*\/\n$/, `\n *\n *  What the half implements. A call returns its result, or a promise of it; it rejects by throwing. */\n`),
+      `export interface ${iface}Plugin {\n`,
+      isView ? `  /** The element the host mounts. The half fills it and follows its size itself. */\n  readonly el: HTMLElement\n` : "",
+      signatures.length ? signatures.join("\n") + "\n" : "",
+      isView
+        ? `  /** The instance goes (the world swapped): release the hardware. */\n  destroy?(): void\n`
+        : `  /** The session closed (the app's close, the world's teardown): stop what it started. */\n  close?(): void\n`,
+      `}\n`,
+    ].join(""))
+
+    // ---- registration + the glue ----
+    const cases = ch.methods.map(m => {
+      const lines: string[] = [`        case ${str(m.name)}: {`]
+      m.args.forEach((a, i) => {
+        const bad = `throw new Error(${str(`bad arguments — ${iface}.${m.name}: ${a.name}`)})`
+        if (a.type.kind !== "optional") {
+          lines.push(`          const a${i} = ${decode(a.type, `args[${i}]`)}`)
+          lines.push(`          if (a${i} === undefined) ${bad}`)
+        } else {
+          const none = a.omit ? "undefined" : "null"
+          lines.push(`          let a${i}: ${webType(a.type.of)} | ${none} = ${none}`)
+          lines.push(`          if (wire.present(args[${i}])) {\n            const r = ${decode(a.type.of, `args[${i}]`)}\n            if (r === undefined) ${bad}\n            a${i} = r\n          }`)
+        }
+      })
+      const call = `plugin.${m.name}(${m.args.map((_, i) => `a${i}`).join(", ")})`
+      if (m.result.kind === "void") lines.push(`          await ${call}\n          return undefined`)
+      else if (!carriesFile(m.result)) lines.push(`          return await ${call}`)
+      else lines.push(`          const r = await ${call}\n          return ${encode(m.result, "r")}`)
+      lines.push(`        }`)
+      return lines.join("\n")
+    })
+    // A payload that holds a File is rewritten on its way out, like a result.
+    const written = (e: LChannel["events"][number]): string => {
+      if (e.inline) {
+        const files = e.inline.filter(f => carriesFile(f.type))
+        if (!files.length) return "payload"
+        return `{ ...payload, ${files.map(f => {
+          const from = at("payload", f.name)
+          return f.type.kind === "optional" && f.omit
+            ? `...(${from} === undefined ? {} : { ${key(f.name)}: ${encode(f.type.of, from)} })`
+            : `${key(f.name)}: ${encode(f.type, from)}`
+        }).join(", ")} }`
+      }
+      return encode(e.payload, "payload")
+    }
+    const emitters = ch.events.map(e =>
+      `      ${key(e.name)}: (${payloadOf(e) === null ? "" : "payload"}) => channel.emit(${str(e.name)}${payloadOf(e) === null ? "" : `, ${written(e)}`}),`)
+    const params = `read${ch.params}(params) ?? {}`
+    out.push([
+      `export const ${iface}Channel = {\n  /** What the halves register under. */\n  name: ${str(ch.name)},\n  /** The contract's version: the highest \`@since\` of its members. */\n  version: ${ch.version},\n} as const\n\n`,
+      isView
+        ? `/** Register the view: \`make\` builds one instance from its params, in the document it is handed. */\n`
+        : `/** Register the service: \`make\` builds one session from its params. It must be cheap — no prompt,\n *  no I/O: that belongs to the first call that needs it. */\n`,
+      `export const register${iface} = (host: PluginHost, make: (params: ${ch.params}, events: ${iface}Events${isView ? ", doc: Document" : ""}) => ${iface}Plugin): void => {\n`,
+      `__BUFFERS__`,
+      `  host.register${isView ? "View" : "Service"}(${iface}Channel.name, (params, channel${isView ? ", doc" : ""}) => {\n`,
+      `    const events: ${iface}Events = {${emitters.length ? "\n" + emitters.join("\n") + "\n    " : ""}}\n`,
+      `    const plugin = make(${params}, events${isView ? ", doc" : ""})\n`,
+      // Reads a call off the wire and hands it to the half; a malformed call never reaches it.
+      `    const call = async (method: string, args: unknown[]): Promise<unknown> => {\n      switch (method) {\n`,
+      cases.length ? cases.join("\n") + "\n" : "",
+      `        default: throw new Error(\`Unknown method: \${method}\`)\n      }\n    }\n`,
+      isView
+        ? `    return { el: plugin.el, call, destroy: () => plugin.destroy?.() }\n`
+        : `    return { call, close: () => plugin.close?.() }\n`,
+      `  }, ${iface}Channel.version)\n}\n`,
+    ].join(""))
+    return out.join("\n")
+  }
+
+  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 header = lowered.channels.map(c => `the ${c.kind} "${c.name}", contract version ${c.version}`).join("; ")
+  const body = [
+    `// ---- the contract's types ----\n\n`,
+    lowered.decls.map(d => guarded(d.name, () => emitDecl(d))).join("\n"),
+    ...lowered.channels.map(ch => `\n// ---- ${ch.iface} ----\n\n${guarded(ch.iface, () => emitChannel(ch))}`),
+  ].join("")
+  const uses = (name: string): boolean => new RegExp(`\\b${name}\\b`).test(body)
+  const views = lowered.channels.some(c => c.kind === "view")
+  const services = lowered.channels.some(c => c.kind === "service")
+
+  return [
+    `// GENERATED by \`lecodes plugin gen\` from contract.d.ts — do not edit.\n`,
+    `// ${opts.id}: ${header}.\n`,
+    `//\n// The web half's side of the channel. This file imports nothing: a half depends on it, on the\n// document it is handed and on the browser.\n\n`,
+    `// ---- what the host hands a half ----\n\n`,
+    `/** Where a half's events go. */\nexport interface PluginChannel { emit(event: string, data?: unknown): void }\n\n`,
+    `/** The host, as a half needs it: a SHAPE — the host's own type is never imported. */\nexport interface PluginHost {\n`,
+    `  // \`version\` = the contract version the half was generated from: what the app's \`supports()\` asks.\n`,
+    views ? `  registerView(name: string, factory: (params: unknown, channel: PluginChannel, doc: Document) => {\n    el: HTMLElement, call?(method: string, args: unknown[]): unknown, destroy?(): void,\n  }, version: number): void\n` : "",
+    services ? `  registerService(name: string, factory: (params: unknown, channel: PluginChannel) => {\n    call?(method: string, args: unknown[]): unknown, close?(): void,\n  }, version: number): void\n` : "",
+    uses("writeFile") ? `  /** Store bytes in the host's buffer table: the handle a File crosses as. */\n  putBuffer(bytes: ArrayBuffer): number\n` : "",
+    uses("readFile") ? `  /** The bytes of a buffer of the host's table — what the handle of a File the app sent names. */\n  getBuffer(systemId: number): ArrayBuffer | Uint8Array | null | undefined\n` : "",
+    `}\n\n`,
+    uses("PluginFile") ? [
+      `/** A \`File\` of the contract. One a half hands to the app: its bytes go into the host's buffer\n *  table, the app gets the handle (a texture source, an upload, a share). One the app hands to a\n *  half: the bytes of the buffer its handle names. */\n`,
+      `export interface PluginFile { data: ArrayBuffer | Uint8Array, name: string }\n\n`,
+    ].join("") : "",
+    uses("writeFile") ? [
+      `const writeFile = (host: PluginHost, file: PluginFile): unknown => {\n`,
+      `  const bytes = file.data instanceof Uint8Array ? file.data.slice().buffer : file.data\n`,
+      `  return { systemId: host.putBuffer(bytes), name: file.name, size: bytes.byteLength }\n}\n\n`,
+    ].join("") : "",
+    uses("Json") ? `/** A value the generator passes through untyped. */\nexport type Json = null | boolean | number | string | Json[] | { [key: string]: Json }\n\n` : "",
+    uses("wire") || uses("readFile") ? WIRE : "",
+    uses("readFile") ? READ_FILE : "",
+    body.replaceAll("__BUFFERS__", uses("readFile") ? `  buffers = (systemId) => host.getBuffer(systemId)\n` : ""),
+  ].join("")
+}
+
+/** The reader of a File the app sent: the host's buffer table is reached through the host a half
+ *  registered with. */
+const READ_FILE = `/** Where the bytes of a File the app sent are: the buffer table of the host a half registered with. */
+let buffers: ((systemId: number) => ArrayBuffer | Uint8Array | null | undefined) | undefined
+
+/** A File the app handed over; undefined when it is not a handle, or the buffer is gone. */
+const readFile = (v: unknown): PluginFile | undefined => {
+  const o = wire.object(v)
+  const id = o ? wire.i32(o.systemId) : undefined
+  const data = id === undefined ? undefined : buffers?.(id)
+  return o && data ? { data, name: wire.string(o.name) ?? "" } : undefined
+}
+
+`
+
+/** The readers of the wire's values: undefined = absent, null, or not that type. */
+const WIRE = `// The readers of the wire's values: undefined = absent, null, or not that type. On the web the wire
+// carries the app's OWN values (the host is JavaScript like the app). What is read of the contract is
+// built anew — a struct, a list, bytes — so what a half keeps is its own; a Json value alone is the
+// app's object, as it is.
+const wire = {
+  present: (v: unknown): boolean => v !== undefined && v !== null,
+  /** A number that is not finite is a null on the wire, as JSON has it. */
+  f64: (v: unknown): number | undefined => typeof v === "number" && Number.isFinite(v) ? v : undefined,
+  i32: (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isInteger(v) && v >= -2147483648 && v <= 2147483647 ? v : undefined,
+  bool: (v: unknown): boolean | undefined => typeof v === "boolean" ? v : undefined,
+  string: (v: unknown): string | undefined => typeof v === "string" ? v : undefined,
+  /** Any JSON value, as it is; a null is a value here. */
+  json: (v: unknown): any => v,
+  /** A copy of the bytes. Told by its class name, not \`instanceof\`: the app's realm may not be the half's. */
+  bytes: (v: unknown): Uint8Array | undefined =>
+    Object.prototype.toString.call(v) === "[object Uint8Array]" ? (v as Uint8Array).slice() : undefined,
+  object: (v: unknown): Record<string, unknown> | undefined =>
+    typeof v === "object" && v !== null && !Array.isArray(v) ? v as Record<string, unknown> : undefined,
+  /** An array of exactly \`count\` values (a tuple), or of any length. */
+  array: (v: unknown, count?: number): unknown[] | undefined =>
+    Array.isArray(v) && (count === undefined || v.length === count) ? v : undefined,
+  /** Every element or nothing: one that does not read fails the list. */
+  list: <T>(v: unknown, each: (v: unknown) => T | undefined): T[] | undefined => {
+    if (!Array.isArray(v)) return undefined
+    const out: T[] = []
+    for (const item of v) {
+      const r = each(item)
+      if (r === undefined) return undefined
+      out.push(r)
+    }
+    return out
+  },
+  map: <T>(v: unknown, each: (v: unknown) => T | undefined): { [key: string]: T } | undefined => {
+    if (typeof v !== "object" || v === null || Array.isArray(v)) return undefined
+    const out: { [key: string]: T } = {}
+    for (const [k, item] of Object.entries(v)) {
+      const r = each(item)
+      if (r === undefined) return undefined
+      out[k] = r
+    }
+    return out
+  },
+}
+
+`

package/src/plugin/generate.ts

@@ -0,0 +1,157 @@
+// `lecodes plugin gen`: the contracts under a path → their generated files. A plugin is a directory
+// with a `contract.d.ts`; the path is one plugin, or a repo that keeps them in `plugins/<id>/`.
+// Generated files are written beside the hand-written ones of the place they travel to
+// (`sdk/<id>.gen.ts`, `ios/<Name>.gen.swift`, `android/…/<Name>.gen.kt`, `web/<id>.gen.ts`) and are
+// committed — `check` is what CI runs.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { basename, join, relative, resolve } from "node:path"
+import type tsModule from "typescript"
+import { CliError } from "../cli"
+import { ContractError, readContract, type Contract } from "./contract"
+import { emitKotlin } from "./emitKotlin"
+import { EmitError, emitSdk } from "./emitSdk"
+import { emitSwift } from "./emitSwift"
+import { emitWeb } from "./emitWeb"
+import { lower } from "./lower"
+import { ManifestError, readManifestIfAny } from "./manifest"
+
+export const CONTRACT_FILE = "contract.d.ts"
+
+export type PluginDir = { id: string, dir: string }
+
+/** The plugins under `path`: itself when it holds a contract, else every `plugins/<id>/` that does. */
+export const findPlugins = (path: string): PluginDir[] => {
+  const root = resolve(path)
+  if (existsSync(join(root, CONTRACT_FILE))) return [{ id: basename(root), dir: root }]
+  const holder = join(root, "plugins")
+  if (!existsSync(holder)) return []
+  return readdirSync(holder).sort()
+    .map(id => ({ id, dir: join(holder, id) }))
+    .filter(p => statSync(p.dir).isDirectory() && existsSync(join(p.dir, CONTRACT_FILE)))
+}
+
+/** The CLI carries no TypeScript: a contract is read with the one its author has — the plugin's own
+ *  (looked up from its directory upwards), else whatever the CLI's install can see. */
+export const loadTypescript = (dir: string): typeof tsModule => {
+  for (const from of [join(dir, "package.json"), import.meta.url]) {
+    try {
+      const mod = createRequire(from)("typescript")
+      const ts = mod?.createSourceFile ? mod : mod?.default   // a runtime may hand the namespace over
+      if (ts?.createSourceFile) return ts
+    } catch { /* the next place */ }
+  }
+  throw new CliError(`Reading a contract needs TypeScript — add it to the plugin's repo: npm install --save-dev typescript`)
+}
+
+export type Generated = { file: string, text: string }
+
+/** Everything one plugin's contract generates, as `path → text`. Throws ContractError / EmitError. */
+export const generatePlugin = (ts: typeof tsModule, plugin: PluginDir): { contract: Contract, files: Generated[] } => {
+  const file = join(plugin.dir, CONTRACT_FILE)
+  const contract = readContract(ts, file, readFileSync(file, "utf8"))
+  // The manifest is held to the folders the plugin has: a half the manifest does not name is built
+  // into no host.
+  readManifestIfAny(plugin.dir, plugin.id)
+  const handWritten = existsSync(join(plugin.dir, "sdk", `${plugin.id}.ts`))
+  const single = contract.channels.length === 1
+  const files: Generated[] = contract.channels.map(channel => ({
+    // One channel is the rule; a contract with several names each file after its channel.
+    file: join(plugin.dir, "sdk", single ? `${plugin.id}.gen.ts` : `${plugin.id}.${channel.iface}.gen.ts`),
+    text: emitSdk(contract, channel, { id: plugin.id, handWritten }),
+  }))
+  // A platform's file is generated where its FOLDER exists: the plugin says which platforms it has
+  // by having them.
+  if (existsSync(join(plugin.dir, "ios"))) {
+    const name = single ? contract.channels[0]!.iface : contract.channels[0]!.iface + "Plugin"
+    files.push({ file: join(plugin.dir, "ios", `${name}.gen.swift`), text: emitSwift(lower(contract), { id: plugin.id }) })
+  }
+  if (existsSync(join(plugin.dir, "android"))) {
+    const name = single ? contract.channels[0]!.iface : contract.channels[0]!.iface + "Plugin"
+    const pkg = kotlinPackage(join(plugin.dir, "android"))
+    files.push({ file: join(pkg.dir, `${name}.gen.kt`), text: emitKotlin(lower(contract), { id: plugin.id, package: pkg.name }) })
+  }
+  if (existsSync(join(plugin.dir, "web"))) {
+    files.push({ file: join(plugin.dir, "web", `${plugin.id}.gen.ts`), text: emitWeb(lower(contract), { id: plugin.id }) })
+    const foreign = hostImports(join(plugin.dir, "web"))
+    if (foreign.length) throw new EmitError(`web/ imports the host — a web half depends on its generated file, the document it is handed and the browser:\n${foreign.map(f => `  ${f}`).join("\n")}`)
+  }
+  return { contract, files }
+}
+
+/** The imports of a web half that name a LeCodes package (`lecodes-sdk`, `lecodes-web-shared`, …), as
+ *  `file:line: the import`. A half that imports its host runs on that host only. */
+export const hostImports = (web: string): string[] => {
+  const found: string[] = []
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir).sort()) {
+      const path = join(dir, entry)
+      if (statSync(path).isDirectory()) { if (entry !== "node_modules" && entry !== "dist") walk(path); continue }
+      if (!/\.(ts|tsx|js|mjs)$/.test(entry)) continue
+      readFileSync(path, "utf8").split("\n").forEach((line, i) => {
+        const m = /(?:from\s+|import\s*\(\s*|import\s+)["'](lecodes-[^"']*)["']/.exec(line)
+        if (m && !/^\s*\/\//.test(line)) found.push(`${relative(join(web, ".."), path)}:${i + 1}: ${m[1]}`)
+      })
+    }
+  }
+  walk(web)
+  return found
+}
+
+/** Where a plugin's Kotlin lives: `android/` is laid out as a Gradle module (its manifest and
+ *  resources travel with the sources), and the generated file is a file of the plugin's PACKAGE —
+ *  the one folder under `src/main/java` that the path narrows down to. */
+export const kotlinPackage = (android: string): { dir: string, name: string } => {
+  const root = join(android, "src", "main", "java")
+  let dir = root
+  while (existsSync(dir)) {
+    const entries = readdirSync(dir).filter(e => !e.startsWith("."))
+    const dirs = entries.filter(e => statSync(join(dir, e)).isDirectory())
+    if (dirs.length !== 1 || entries.length !== 1) break
+    dir = join(dir, dirs[0]!)
+  }
+  if (dir === root) {
+    throw new EmitError(`android/ has no package yet — make the folder of the plugin's Kotlin package (android/src/main/java/com/example/plugin), the generated file is written into it`)
+  }
+  return { dir, name: relative(root, dir).split(/[\\/]/).join(".") }
+}
+
+export type GenReport = {
+  plugins: { id: string, contract: Contract, written: string[], stale: string[], fresh: string[] }[]
+  /** Contracts that did not read or emit, as printable text. */
+  failures: string[]
+}
+
+/** Generate (or, with `check`, compare) every plugin under `path`. Paths in the report are relative
+ *  to `path`. A failed contract does not stop the others. */
+export const generate = (path: string, opts: { check?: boolean } = {}): GenReport => {
+  const plugins = findPlugins(path)
+  if (plugins.length === 0) throw new CliError(`No plugin under ${resolve(path)}: a plugin is a directory with a ${CONTRACT_FILE} (one, or plugins/<id>/ of a repo).`)
+  const ts = loadTypescript(plugins[0]!.dir)
+  const root = resolve(path)
+  const report: GenReport = { plugins: [], failures: [] }
+
+  for (const plugin of plugins) {
+    try {
+      const { contract, files } = generatePlugin(ts, plugin)
+      const entry = { id: plugin.id, contract, written: [] as string[], stale: [] as string[], fresh: [] as string[] }
+      for (const f of files) {
+        const name = relative(root, f.file) || basename(f.file)
+        const current = existsSync(f.file) ? readFileSync(f.file, "utf8") : null
+        if (current === f.text) { entry.fresh.push(name); continue }
+        if (opts.check) { entry.stale.push(name); continue }
+        mkdirSync(join(f.file, ".."), { recursive: true })
+        writeFileSync(f.file, f.text)
+        entry.written.push(name)
+      }
+      report.plugins.push(entry)
+    } catch (e) {
+      if (e instanceof ContractError) report.failures.push(e.problems.map(p => `${relative(root, e.file) || e.file}:${p.line}: ${p.message}`).join("\n"))
+      else if (e instanceof EmitError) report.failures.push(`${relative(root, join(plugin.dir, CONTRACT_FILE))}: ${e.message}`)
+      else if (e instanceof ManifestError) report.failures.push(`${relative(root, e.file) || e.file}:\n${e.problems.map(p => `  ${p}`).join("\n")}`)
+      else throw e
+    }
+  }
+  return report
+}

package/src/plugin/lines.ts

@@ -0,0 +1,28 @@
+// How the native emitters (emitSwift.ts, emitKotlin.ts) lay generated code out: a codec is a LIST
+// OF LINES, indented relative to where it is put. A statement has a line of its own; what nests is
+// indented — generated code is read when a plugin is debugged, and then it is read like any other.
+
+export const INDENT = "    "
+
+/** `lines` one level (or `by`) deeper. */
+export const indent = (lines: string[], by = INDENT): string[] => lines.map(l => l === "" ? l : by + l)
+
+/** `head` … `tail` around `inner`: on ONE line when `inner` is one short statement, else as a block. */
+export const block = (head: string, inner: string[], tail: string): string[] => {
+  const one = `${head} ${inner[0]} ${tail}`
+  return inner.length === 1 && one.length <= 100 ? [one] : [head, ...indent(inner), tail]
+}
+
+/** An expression of several lines in its place: `before` its first line, `after` its last. */
+export const wrap = (before: string, lines: string[], after: string): string[] =>
+  lines.map((l, i) => `${i === 0 ? before : ""}${l}${i === lines.length - 1 ? after : ""}`)
+
+/** `lines` as text, each `by` deep. */
+export const text = (lines: string[], by: string): string => indent(lines, by).join("\n")
+
+/** A name for the wire's writer that none of `names` (the identifiers in its scope) has. */
+export const writerName = (names: string[]): string => {
+  let w = "w"
+  while (names.includes(w)) w += "_"
+  return w
+}