lecodes-cli 1.0.0 → 2.0.0

package/src/plugin/lower.ts

@@ -0,0 +1,231 @@
+// The contract's model → the model of the NATIVE emitters (Swift, Kotlin): every type a native
+// language must declare has a NAME. TypeScript writes `{ message: string }`, `"front" | "back"` and
+// `f64 | string` in place; Swift and Kotlin need a struct, an enum and a tagged union for them, so
+// the anonymous ones are named after where they stand (`PushStatus.permission` →
+// `PushStatusPermission`) and the aliases are resolved.
+//
+// Also decided here, once for both languages: `T | null` and an optional member are ONE thing on
+// the native side (an optional), and a union is told apart by what its members are on the wire —
+// a union the wire cannot tell apart is refused.
+
+import type { Channel, Contract, Decl, Field, Type } from "./contract"
+import { EmitError } from "./emitSdk"
+
+export type Scalar = "i32" | "f64" | "boolean" | "string" | "json" | "file" | "bytes" | "void"
+
+export type L =
+  | { kind: Scalar }
+  | { kind: "enum" | "struct" | "union", name: string }
+  | { kind: "list" | "map" | "optional", of: L }
+  | { kind: "tuple", of: L[] }
+
+export type LField = {
+  name: string
+  /** `optional` when the member may be absent or null. */
+  type: L
+  /** Absent when nil (an optional member); a null on the wire otherwise (`T | null`). */
+  omit: boolean
+  doc: string
+}
+
+export type LDecl =
+  | { kind: "enum", name: string, values: string[], doc: string }
+  | { kind: "struct", name: string, fields: LField[], doc: string }
+  | { kind: "union", name: string, members: L[], doc: string }
+
+/** `omit`: the argument may be left out (`name?:`); a nullable one (`T | null`) is always named. */
+export type LArg = { name: string, type: L, omit: boolean }
+
+export type LMethod = { name: string, args: LArg[], result: L, since: number, rejects: string[], doc: string }
+
+export type LEvent = {
+  name: string
+  payload: L
+  /** The payload was written in place (`error: { message: string }`): its members are the
+   *  arguments of the event's function, no struct is declared for it. */
+  inline?: LField[]
+  since: number
+  doc: string
+}
+
+export type LChannel = {
+  kind: "view" | "service"
+  name: string
+  iface: string
+  version: number
+  /** The struct of the params; the channel declares an empty one when the marker names none. */
+  params: string
+  methods: LMethod[]
+  events: LEvent[]
+  /** Every code a method of the channel rejects with, in the order they appear. */
+  codes: string[]
+  doc: string
+}
+
+export type Lowered = { decls: LDecl[], channels: LChannel[] }
+
+const upper = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1)
+
+/** What a value is on the wire — two members of a union must differ in it, which is how a reader
+ *  tells them apart: by what the value at hand IS, before it reads it. */
+export const wireClass = (t: L): string => {
+  switch (t.kind) {
+    case "i32": case "f64": return "number"
+    case "string": case "enum": return "string"
+    case "boolean": return "boolean"
+    case "struct": case "map": return "object"
+    case "list": case "tuple": return "array"
+    default: return t.kind
+  }
+}
+
+export const lower = (contract: Contract): Lowered => {
+  const source = new Map<string, Decl>(contract.decls.map(d => [d.name, d]))
+  const decls = new Map<string, LDecl>()
+  const resolving = new Set<string>()
+  const aliases = new Map<string, L>()
+
+  const addDecl = (d: LDecl, where: string): void => {
+    const taken = decls.get(d.name)
+    if (taken && JSON.stringify(taken) !== JSON.stringify(d)) {
+      throw new EmitError(`${where}: the name ${d.name} the generator gives this type is taken — name the type yourself (export type ${d.name}… = …)`)
+    }
+    decls.set(d.name, d)
+  }
+
+  const fields = (list: Field[], owner: string): LField[] => list.map(f => {
+    const t = type(f.type, `${owner}${upper(f.name)}`, `${owner}.${f.name}`)
+    const optional = f.optional || t.kind === "optional"
+    return { name: f.name, type: optional && t.kind !== "optional" ? { kind: "optional", of: t } : t, omit: f.optional, doc: f.doc }
+  })
+
+  /** `name`: what an anonymous type is called if this one needs a declaration. */
+  const type = (t: Type, name: string, where: string): L => {
+    switch (t.kind) {
+      case "ref": return named(t.name, where)
+      case "literals": addDecl({ kind: "enum", name, values: t.values, doc: "" }, where); return { kind: "enum", name }
+      case "object": addDecl({ kind: "struct", name, fields: fields(t.fields, name), doc: "" }, where); return { kind: "struct", name }
+      case "map": return { kind: "map", of: type(t.of, `${name}Value`, where) }
+      case "list": return { kind: "list", of: type(t.of, `${name}Item`, where) }
+      case "tuple": return { kind: "tuple", of: t.of.map((m, i) => type(m, `${name}${i}`, where)) }
+      case "nullable": {
+        const of = type(t.of, name, where)
+        return of.kind === "optional" ? of : { kind: "optional", of }
+      }
+      case "union": {
+        const members = t.of.map((m, i) => type(m, `${name}${upper(memberLabel(m, i))}`, where))
+        const seen = new Map<string, L>()
+        for (const m of members) {
+          if (m.kind === "json" || m.kind === "file" || m.kind === "bytes" || m.kind === "optional" || m.kind === "union") {
+            throw new EmitError(`${where}: a union holds scalars, enums, structs, lists — not ${m.kind === "optional" ? "a nullable member" : m.kind}`)
+          }
+          const c = wireClass(m)
+          if (seen.has(c)) throw new EmitError(`${where}: two members of the union are both a ${c} on the wire — a half cannot tell them apart`)
+          seen.set(c, m)
+        }
+        addDecl({ kind: "union", name, members, doc: "" }, where)
+        return { kind: "union", name }
+      }
+      default: return { kind: t.kind }
+    }
+  }
+
+  const memberLabel = (t: Type, i: number): string => t.kind === "ref" ? t.name : t.kind === "literals" ? "name" : `${t.kind}${i}`
+
+  /** A declaration of the contract by its name: a struct, or an alias resolved to what it names. */
+  const named = (name: string, where: string): L => {
+    const d = source.get(name)!
+    if (d.kind === "struct") {
+      if (!decls.has(name) && !resolving.has(name)) {
+        resolving.add(name)
+        const f = fields(d.fields, name)
+        resolving.delete(name)
+        addDecl({ kind: "struct", name, fields: f, doc: d.doc }, where)
+      }
+      return { kind: "struct", name }
+    }
+    const known = aliases.get(name)
+    if (known) return known
+    if (resolving.has(name)) throw new EmitError(`${where}: the alias ${name} names itself`)
+    resolving.add(name)
+    const l = type(d.type, name, name)
+    resolving.delete(name)
+    aliases.set(name, l)
+    const own = decls.get(name)
+    if (own && own.doc === "" && d.doc) decls.set(name, { ...own, doc: d.doc })
+    return l
+  }
+
+  const channels = contract.channels.map((ch: Channel): LChannel => {
+    const iface = ch.iface
+    const params = ch.paramsType ?? `${iface}Params`
+    if (ch.paramsType) named(ch.paramsType, iface)
+    else addDecl({ kind: "struct", name: params, fields: [], doc: "" }, iface)
+
+    const methods = ch.methods.map((m): LMethod => {
+      const where = `${iface}.${m.name}`
+      return {
+        name: m.name,
+        args: m.args.map(a => {
+          const t = type(a.type, `${iface}${upper(m.name)}${upper(a.name)}`, `${where}(${a.name})`)
+          return { name: a.name, type: a.optional && t.kind !== "optional" ? { kind: "optional", of: t } : t, omit: a.optional }
+        }),
+        result: m.result.kind === "void" ? { kind: "void" } : type(m.result, `${iface}${upper(m.name)}Result`, `${where}()`),
+        since: m.since, rejects: m.rejects, doc: m.doc,
+      }
+    })
+
+    const events = ch.events.map((e): LEvent => {
+      const where = `${iface} event ${e.name}`
+      if (e.payload.kind === "object") {
+        return { name: e.name, payload: { kind: "void" }, inline: fields(e.payload.fields, `${iface}${upper(e.name)}`), since: e.since, doc: e.doc }
+      }
+      return { name: e.name, payload: e.payload.kind === "void" ? { kind: "void" } : type(e.payload, `${iface}${upper(e.name)}Payload`, where), since: e.since, doc: e.doc }
+    })
+
+    const codes: string[] = []
+    for (const m of methods) for (const c of m.rejects) if (!codes.includes(c)) codes.push(c)
+    return { kind: ch.kind, name: ch.name, iface, version: ch.version, params, methods, events, codes, doc: ch.doc }
+  })
+
+  // Only what a channel reaches is declared: a struct of the contract nothing names is not a type
+  // a half ever sees.
+  return { decls: [...decls.values()], channels }
+}
+
+/** Which way a declaration crosses: the app SENDS it (an argument, a param) → it is read here; the
+ *  plugin sends it (a result, an event) → it is written here. Only the codec a way needs is
+ *  emitted by a native emitter — a struct that carries a File is written, never read. */
+export type Ways = { read: Set<string>, write: Set<string> }
+
+export const waysOf = (lowered: Lowered): Ways => {
+  const byName = new Map(lowered.decls.map(d => [d.name, d]))
+  const ways: Ways = { read: new Set(), write: new Set() }
+  const walk = (t: L, set: Set<string>): void => {
+    switch (t.kind) {
+      case "list": case "map": case "optional": walk(t.of, set); return
+      case "tuple": t.of.forEach(m => walk(m, set)); return
+      case "enum": case "struct": case "union": {
+        if (set.has(t.name)) return
+        set.add(t.name)
+        const d = byName.get(t.name)!
+        if (d.kind === "struct") d.fields.forEach(f => walk(f.type, set))
+        if (d.kind === "union") d.members.forEach(m => walk(m, set))
+        return
+      }
+      default: return
+    }
+  }
+  for (const ch of lowered.channels) {
+    walk({ kind: "struct", name: ch.params }, ways.read)
+    for (const m of ch.methods) {
+      m.args.forEach(a => walk(a.type, ways.read))
+      walk(m.result, ways.write)
+    }
+    for (const e of ch.events) {
+      walk(e.payload, ways.write)
+      e.inline?.forEach(f => walk(f.type, ways.write))
+    }
+  }
+  return ways
+}

package/src/plugin/manifest.ts

@@ -0,0 +1,192 @@
+// A plugin's manifest (`lecodes-plugin.json`, 2.x): what a host needs to BUILD the plugin in — the
+// type that registers each half, what a half asks of its platform (usage strings, entitlements,
+// packages, Gradle dependencies, bundler resources). What the plugin DOES is not here: the channels,
+// their names and their types are the contract's (contract.d.ts), the folders are the convention
+// (`sdk/`, `ios/`, `android/`, `web/`).
+//
+// A platform is a key of the manifest, ALWAYS: an object where the plugin has a half, `null` where
+// it has none. A missing key is refused — "not supported" is a statement, not an omission.
+//
+// Desktop plugins are another system (a prebuilt library behind a C ABI) with a manifest of their
+// own shape; nothing of it is read here.
+
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { join } from "node:path"
+
+export const MANIFEST_FILE = "lecodes-plugin.json"
+
+/** A SwiftPM dependency the iOS half links. */
+export type IosPackage = { url: string, exact?: string, from?: string, products: string[] }
+
+/** What a web half asks of its bundler: a file of a package, handed over as a URL of a script that
+ *  stands alone (`worker-url`), as a URL (`url`) or as its text (`text`). */
+export type WebResource = { module: string, as: "worker-url" | "url" | "text" }
+
+export type PluginManifest = {
+  id: string
+  name: string
+  version: string
+  /** The SDK the plugin is written for, as a range of its ONE version (`^2.0.0`): the major is the
+   *  contract between a bundle, the runtime and a half. */
+  sdk: string
+  description?: string
+  ios: {
+    /** The Swift module the half is built as in a shell. Default: `LeCodes` + the id in PascalCase. */
+    module?: string
+    /** The type with `static func register(in: LeCodesEngine)`. */
+    register: string
+    infoPlist?: Record<string, string>
+    entitlements?: Record<string, unknown>
+    packages?: IosPackage[]
+  } | null
+  android: {
+    /** The Gradle module the half is built as in a shell. Default: `lecodes-` + the id. */
+    module?: string
+    /** The object with `fun register(engine: LecodesEngine, context: Context)`, by its full name. */
+    register: string
+    /** Maven coordinates; a `platform:` prefix is a BoM. */
+    dependencies?: string[]
+    /** App-level Gradle plugins the shell applies (`com.google.gms.google-services`). */
+    gradlePlugins?: string[]
+  } | null
+  web: {
+    /** The module that exports `register(host, resources?)`, relative to the plugin. */
+    register: string
+    /** npm packages the half imports, as a package.json's dependencies. */
+    dependencies?: Record<string, string>
+    /** The half's bundler resources, by the name `register` receives them under. */
+    resources?: Record<string, WebResource>
+  } | null
+}
+
+export class ManifestError extends Error {
+  constructor(readonly file: string, readonly problems: string[]) {
+    super(`${file}:\n${problems.map(p => `  ${p}`).join("\n")}`)
+  }
+}
+
+const ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+const VERSION = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/
+const RANGE = /^[\^~]?\d+\.\d+\.\d+$/
+const PLATFORMS = ["ios", "android", "web"] as const
+const KNOWN = new Set(["id", "name", "version", "sdk", "description", ...PLATFORMS])
+const GONE: Record<string, string> = {
+  provides: "the channels are the contract's (contract.d.ts)",
+  js: "the wrapper is found by convention (sdk/)",
+  desktop: "desktop plugins are another system, with a manifest of their own",
+}
+const BRANCH: Record<(typeof PLATFORMS)[number], Set<string>> = {
+  ios: new Set(["module", "register", "infoPlist", "entitlements", "packages"]),
+  android: new Set(["module", "register", "dependencies", "gradlePlugins"]),
+  web: new Set(["register", "dependencies", "resources"]),
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const isFolder = (path: string): boolean => existsSync(path) && statSync(path).isDirectory()
+
+export const pascal = (id: string): string => id.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join("")
+
+/** The manifest of the plugin in `dir` (its folder's name is its id). Every problem of the file is
+ *  reported at once. */
+export const readManifest = (dir: string, id: string): PluginManifest => {
+  const file = join(dir, MANIFEST_FILE)
+  let raw: unknown
+  try { raw = JSON.parse(readFileSync(file, "utf8").replace(/^/, "")) } catch (e) {
+    throw new ManifestError(file, [`not JSON: ${e instanceof Error ? e.message : String(e)}`])
+  }
+  if (!isObject(raw)) throw new ManifestError(file, ["a manifest is an object"])
+
+  const problems: string[] = []
+  const text = (key: string, of: Record<string, unknown> = raw, where = ""): string | undefined => {
+    const v = of[key]
+    if (typeof v === "string" && v.trim() !== "") return v
+    problems.push(`${where}${key}: ${v === undefined ? "missing" : "a text"}`)
+    return undefined
+  }
+
+  for (const key of Object.keys(raw)) {
+    if (GONE[key]) problems.push(`${key}: gone in 2.x — ${GONE[key]}`)
+    else if (!KNOWN.has(key)) problems.push(`${key}: not a key of a manifest`)
+  }
+  if (text("id") !== undefined && raw.id !== id) problems.push(`id: "${String(raw.id)}" — the plugin's folder is "${id}", and the folder is the id`)
+  if (!ID.test(id)) problems.push(`id: "${id}" — lower-case words joined by "-"`)
+  text("name")
+  const version = text("version")
+  if (version !== undefined && !VERSION.test(version)) problems.push(`version: "${version}" — a version is 2.0.0`)
+  const sdk = text("sdk")
+  if (sdk !== undefined && !RANGE.test(sdk)) problems.push(`sdk: "${sdk}" — a range of the SDK's version: ^2.0.0`)
+  if (raw.description !== undefined && typeof raw.description !== "string") problems.push("description: a text")
+
+  for (const platform of PLATFORMS) {
+    const branch = raw[platform]
+    const folder = isFolder(join(dir, platform))
+    if (branch === undefined) { problems.push(`${platform}: missing — an object, or null where the plugin has no ${platform} half`); continue }
+    if (branch === null) {
+      if (folder) problems.push(`${platform}: null, and the plugin has a ${platform}/ folder`)
+      continue
+    }
+    if (!isObject(branch)) { problems.push(`${platform}: an object, or null`); continue }
+    if (!folder) problems.push(`${platform}: the plugin has no ${platform}/ folder — say null`)
+    for (const key of Object.keys(branch)) {
+      if (key === "sources" || key === "minSdk") problems.push(`${platform}.${key}: gone in 2.x — ${key === "sources" ? `the half is the ${platform}/ folder` : "the SDK a plugin needs is `sdk`, one for every platform"}`)
+      else if (!BRANCH[platform].has(key)) problems.push(`${platform}.${key}: not a key of a manifest`)
+    }
+    const register = text("register", branch, `${platform}.`)
+    if (platform === "android" && register !== undefined && !/^[A-Za-z_][\w]*(\.[A-Za-z_][\w]*)+$/.test(register)) {
+      problems.push(`android.register: "${register}" — the object's full name (com.example.plugin.Plugin)`)
+    }
+    if (platform === "ios" && register !== undefined && !/^[A-Za-z_]\w*$/.test(register)) problems.push(`ios.register: "${register}" — a type's name`)
+    if (platform === "web" && register !== undefined) {
+      if (!register.startsWith("web/")) problems.push(`web.register: "${register}" — a module of the web/ folder`)
+      else if (!existsSync(join(dir, register))) problems.push(`web.register: ${register} is not there`)
+    }
+  }
+
+  const ios = isObject(raw.ios) ? raw.ios : null
+  if (ios) {
+    for (const key of ["infoPlist"] as const) {
+      const v = ios[key]
+      if (v !== undefined && (!isObject(v) || Object.values(v).some(x => typeof x !== "string"))) problems.push(`ios.${key}: a key → a text`)
+    }
+    if (ios.entitlements !== undefined && !isObject(ios.entitlements)) problems.push("ios.entitlements: an object")
+    if (ios.packages !== undefined) {
+      if (!Array.isArray(ios.packages)) problems.push("ios.packages: a list")
+      else ios.packages.forEach((p, i) => {
+        if (!isObject(p) || typeof p.url !== "string" || !Array.isArray(p.products) || p.products.length === 0 || p.products.some(x => typeof x !== "string")) {
+          problems.push(`ios.packages[${i}]: { url, exact | from, products }`)
+        } else if ((typeof p.exact === "string") === (typeof p.from === "string")) {
+          problems.push(`ios.packages[${i}]: one of exact and from`)
+        }
+      })
+    }
+  }
+  const android = isObject(raw.android) ? raw.android : null
+  if (android) {
+    for (const key of ["dependencies", "gradlePlugins"] as const) {
+      const v = android[key]
+      if (v !== undefined && (!Array.isArray(v) || v.some(x => typeof x !== "string"))) problems.push(`android.${key}: a list of texts`)
+    }
+  }
+  const web = isObject(raw.web) ? raw.web : null
+  if (web) {
+    const deps = web.dependencies
+    if (deps !== undefined && (!isObject(deps) || Object.values(deps).some(x => typeof x !== "string"))) problems.push("web.dependencies: a package → its range")
+    const resources = web.resources
+    if (resources !== undefined) {
+      if (!isObject(resources)) problems.push("web.resources: a name → { module, as }")
+      else for (const [name, r] of Object.entries(resources)) {
+        if (!/^[A-Za-z_]\w*$/.test(name)) problems.push(`web.resources.${name}: a name the half reads it under`)
+        if (!isObject(r) || typeof r.module !== "string" || (r.as !== "worker-url" && r.as !== "url" && r.as !== "text")) {
+          problems.push(`web.resources.${name}: { module, as: "worker-url" | "url" | "text" }`)
+        }
+      }
+    }
+  }
+
+  if (problems.length) throw new ManifestError(file, problems)
+  return raw as unknown as PluginManifest
+}
+
+/** The manifest, or null where the plugin has none yet (a contract is where a plugin starts). */
+export const readManifestIfAny = (dir: string, id: string): PluginManifest | null =>
+  existsSync(join(dir, MANIFEST_FILE)) ? readManifest(dir, id) : null