lecodes-cli 1.0.0 → 2.0.1

package/src/hosts/peers.ts

@@ -10,7 +10,7 @@ import { dirname, join, resolve } from "node:path"
  *            peers (a project-local `-D` install is invisible to it).
  *   prefix   ~/.lecodes/peers (LECODES_PEERS_DIR) — the CLI's own install dir, filled ON FIRST USE by
  *            peerInstall.ts when a command needs a peer that isn't there: no admin rights, and the
- *            runtime-set peer (lecodes-renderer) is pinned to THIS CLI's version, so the compiler and
+ *            runtime-set peer (lecodes-headless) is pinned to THIS CLI's version, so the compiler and
  *            the headless host can't drift apart. `@napi-rs/canvas` (PNG output) rides along with it.
  *
  * Global wins when both exist (it is what the user chose by hand). `--version` reports each peer's
@@ -18,7 +18,7 @@ import { dirname, join, resolve } from "node:path"
  * errors or a design screen rendering empty — is visible at a glance. The probe is an export subpath
  * that resolves to a real file in BOTH the published package and the workspace source. */
 export const OPTIONAL_PEERS: [name: string, probe: string][] = [
-  ["lecodes-renderer", "lecodes-renderer/headless"],
+  ["lecodes-headless", "lecodes-headless/headless"],
   ["lecodes-design", "lecodes-design/server"],
   ["lecodes-3d-editor", "lecodes-3d-editor/server"],
   ["lecodes-assets", "lecodes-assets/cli"],

package/src/index.ts

@@ -1,6 +1,7 @@
 import { existsSync, realpathSync } from "node:fs"
 import { delimiter, dirname, join } from "node:path"
 import pkg from "../package.json"
+import { SDK_VERSION } from "lecodes-sdk/version"
 import { c, log, reportError, runCli } from "./cli"
 import { commandGroups } from "./commands"
 import { installedDesktopVersions, selectedDesktopVersion } from "./hosts/desktopRenderer"
@@ -39,7 +40,9 @@ const INSTALLED = STANDALONE && (() => {
 /** `--version`: the CLI, every separately-installed optional peer (or "not installed"), and the
  *  desktop host / matc `render --desktop` and the shader compile would use (cache state, no network). */
 const printVersion = (): void => {
-  const rows: [string, string][] = [["lecodes-cli", pkg.version ?? "unknown"]]
+  // The SDK the CLI compiles with: its major is stamped into every bundle (`// sdk:`) and is what a
+  // host must match to run it — the number to compare with `lecodes-desktop --version`'s SDK.
+  const rows: [string, string][] = [["lecodes-cli", pkg.version ?? "unknown"], ["lecodes-sdk", SDK_VERSION]]
   for (const [name, probe] of OPTIONAL_PEERS) {
     const version = peerVersion(name, probe)
     const where = peerSource(name, probe)

package/src/plugin/contract.ts

@@ -0,0 +1,438 @@
+// A plugin's `contract.d.ts` → the MODEL every emitter of the plugin generator works from
+// (docs/plans/plugins-plan.md in core). The contract is the wire of one or more channels: per
+// channel an interface that extends a marker (`View<name, Params, Events>` /
+// `Service<name, Params, Events>`), plus the structs, enums and aliases its members name.
+//
+// Read from the SYNTAX tree, no type checker (the gen-bridges rule): the markers, the params and
+// the events are found by what the file says, never by what a name resolves to. That is also why
+// the reader is strict — a contract is written by third parties, and what it does not understand
+// must be an error with a line, never a silent `any`.
+//
+// `ts` is passed in: the CLI has no TypeScript of its own and loads the plugin repo's.
+
+import type tsModule from "typescript"
+
+export type Scalar = "i32" | "f64" | "boolean" | "string" | "bytes" | "file" | "json" | "void"
+
+export type Type =
+  | { kind: Scalar }
+  /** A struct / an alias this contract declares. */
+  | { kind: "ref", name: string }
+  /** An inline union of string literals (a named one is an alias of it). */
+  | { kind: "literals", values: string[] }
+  /** An inline object type. */
+  | { kind: "object", fields: Field[] }
+  /** `{ [key: string]: T }` */
+  | { kind: "map", of: Type }
+  | { kind: "list", of: Type }
+  | { kind: "tuple", of: Type[] }
+  /** Two or more members, never null (see `nullable`). */
+  | { kind: "union", of: Type[] }
+  /** `T | null` */
+  | { kind: "nullable", of: Type }
+
+export type Field = { name: string, type: Type, optional: boolean, doc: string }
+
+export type Decl =
+  | { kind: "struct", name: string, fields: Field[], doc: string, line: number }
+  | { kind: "alias", name: string, type: Type, doc: string, line: number }
+
+export type Arg = { name: string, type: Type, optional: boolean }
+
+export type Method = {
+  name: string
+  args: Arg[]
+  /** What the promise resolves to; `void` for none. */
+  result: Type
+  /** The contract version that added it (`@since`), 1 when untagged. */
+  since: number
+  /** The codes the call can fail with (`@rejects`). */
+  rejects: string[]
+  doc: string
+  line: number
+}
+
+export type Event = { name: string, payload: Type, since: number, doc: string, line: number }
+
+export type Channel = {
+  kind: "view" | "service"
+  /** What the halves register under: `registerView(name)`. */
+  name: string
+  /** The interface's name — the prefix of every generated name. */
+  iface: string
+  /** The params struct's fields (empty when the marker names none). */
+  params: Field[]
+  /** The interfaces the marker names, as the contract exports them. */
+  paramsType?: string
+  eventsType?: string
+  events: Event[]
+  methods: Method[]
+  /** The highest `@since` of its members: what a half reports when it registers. */
+  version: number
+  doc: string
+  line: number
+}
+
+export type Contract = { file: string, channels: Channel[], decls: Decl[] }
+
+export type Problem = { line: number, message: string }
+
+export class ContractError extends Error {
+  readonly file: string
+  readonly problems: Problem[]
+  constructor(file: string, problems: Problem[]) {
+    super(problems.map(p => `${file}:${p.line}: ${p.message}`).join("\n"))
+    this.name = "ContractError"
+    this.file = file
+    this.problems = problems
+  }
+}
+
+/** The module a contract imports its vocabulary from, and the names it may take. */
+export const CONTRACT_MODULE = "lecodes-sdk/plugin"
+const MARKERS: Record<string, Channel["kind"]> = { View: "view", Service: "service" }
+const VOCABULARY: Record<string, Scalar> = { i32: "i32", f64: "f64", File: "file", Json: "json" }
+
+/** Names a contract may not declare: the generated code of every language would shadow a global. */
+const RESERVED = new Set([
+  "Array", "Boolean", "Date", "Error", "File", "Function", "Json", "Map", "Number", "Object", "Promise", "Record",
+  "Service", "Set", "String", "Symbol", "Uint8Array", "View",
+  // What a native half's generated file names: the types of Swift and Kotlin, the host's support types.
+  "Any", "Bool", "Data", "Double", "Int", "Int32", "List", "Pair", "Triple", "Unit", "Void",
+  "NoCode", "PluginFile", "Reply", "Wire",
+])
+
+/** A method or an argument becomes an identifier in TypeScript, Swift and Kotlin. */
+const KEYWORDS = new Set([
+  "as", "break", "case", "catch", "class", "const", "continue", "default", "delete", "do", "else", "enum", "export",
+  "extends", "false", "finally", "for", "fun", "func", "function", "if", "import", "in", "init", "interface", "internal",
+  "is", "let", "new", "null", "object", "package", "private", "protocol", "public", "return", "self", "static", "struct",
+  "super", "switch", "this", "throw", "true", "try", "typeof", "val", "var", "void", "when", "while", "with",
+])
+/** Members of the wrapper's bases a method would replace. */
+const TAKEN = new Set(["call", "on", "off", "open", "close", "destroy", "style", "constructor"])
+
+const TAGS = new Set(["since", "rejects"])
+
+export const readContract = (ts: typeof tsModule, file: string, text: string): Contract => {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true)
+  const problems: Problem[] = []
+  const lineOf = (n: tsModule.Node): number => sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1
+  const fail = (n: tsModule.Node, message: string): void => { problems.push({ line: lineOf(n), message }) }
+
+  // ---- pass 1: what the file declares and imports -------------------------------------------------
+  const imported = new Set<string>()
+  const interfaces = new Map<string, tsModule.InterfaceDeclaration>()
+  const aliases = new Map<string, tsModule.TypeAliasDeclaration>()
+
+  for (const s of sf.statements) {
+    if (ts.isImportDeclaration(s)) {
+      const from = ts.isStringLiteral(s.moduleSpecifier) ? s.moduleSpecifier.text : ""
+      if (from !== CONTRACT_MODULE) { fail(s, `a contract imports from "${CONTRACT_MODULE}" only (got "${from}")`); continue }
+      const clause = s.importClause
+      const named = clause?.namedBindings && ts.isNamedImports(clause.namedBindings) ? clause.namedBindings : undefined
+      if (!clause || !named || clause.name) { fail(s, `write the import as \`import type { … } from "${CONTRACT_MODULE}"\``); continue }
+      for (const e of named.elements) {
+        if (e.propertyName) { fail(e, `import "${e.propertyName.text}" under its own name — the generator reads names, not what they resolve to`); continue }
+        const name = e.name.text
+        if (!(name in MARKERS) && !(name in VOCABULARY)) fail(e, `"${CONTRACT_MODULE}" has no "${name}" for a contract (it has ${[...Object.keys(MARKERS), ...Object.keys(VOCABULARY)].join(", ")})`)
+        imported.add(name)
+      }
+      continue
+    }
+    if (ts.isInterfaceDeclaration(s) || ts.isTypeAliasDeclaration(s)) {
+      const name = s.name.text
+      if (RESERVED.has(name)) fail(s.name, `"${name}" is taken by a global or by the contract's vocabulary — pick another name`)
+      if (interfaces.has(name) || aliases.has(name)) fail(s.name, `"${name}" is declared twice`)
+      if (s.typeParameters?.length) fail(s.name, `"${name}": a contract declares no generic types`)
+      if (ts.isInterfaceDeclaration(s)) interfaces.set(name, s)
+      else aliases.set(name, s)
+      continue
+    }
+    fail(s, "a contract holds type imports, interfaces and type aliases only")
+  }
+
+  // ---- docs and tags ------------------------------------------------------------------------------
+  const docOf = (n: tsModule.Node): string => {
+    const docs = ts.getJSDocCommentsAndTags(n).filter(ts.isJSDoc)
+    return docs.map(d => ts.getTextOfJSDocComment(d.comment) ?? "").filter(Boolean).join("\n").trim()
+  }
+  const tagsOf = (n: tsModule.Node): { since: number, rejects: string[] } => {
+    let since = 1
+    const rejects: string[] = []
+    for (const tag of ts.getJSDocTags(n)) {
+      const name = tag.tagName.text
+      const value = (ts.getTextOfJSDocComment(tag.comment) ?? "").trim()
+      if (!TAGS.has(name)) { fail(tag, `unknown tag @${name} (a contract knows ${[...TAGS].map(t => "@" + t).join(", ")})`); continue }
+      if (name === "since") {
+        if (!/^[1-9]\d*$/.test(value)) fail(tag, `@since takes a contract version: a whole number from 1 (got "${value}")`)
+        else since = Number(value)
+      } else {
+        const codes = value.split(/[\s,]+/).filter(Boolean)
+        if (codes.length === 0) fail(tag, "@rejects lists the codes a call can fail with")
+        for (const code of codes) {
+          if (!/^[a-z][A-Za-z0-9]*$/.test(code)) fail(tag, `@rejects: "${code}" is not a code (camelCase, a letter first)`)
+          else if (!rejects.includes(code)) rejects.push(code)
+        }
+      }
+    }
+    return { since, rejects }
+  }
+
+  // ---- types ---------------------------------------------------------------------------------------
+  const VOID: Type = { kind: "void" }
+  const JSON_TYPE: Type = { kind: "json" }
+
+  const readFields = (members: tsModule.NodeArray<tsModule.TypeElement>, owner: string): Field[] => {
+    const fields: Field[] = []
+    for (const m of members) {
+      if (ts.isMethodSignature(m)) { fail(m, `${owner}: a method belongs to an interface that extends View<…> or Service<…>`); continue }
+      if (ts.isIndexSignatureDeclaration(m)) { fail(m, `${owner}: an index signature stands alone — \`{ [key: string]: T }\` as the member's whole type`); continue }
+      if (!ts.isPropertySignature(m) || !m.type || !(ts.isIdentifier(m.name) || ts.isStringLiteral(m.name))) { fail(m, `${owner}: a member is \`name: Type\` or \`name?: Type\``); continue }
+      const name = m.name.text
+      if (fields.some(f => f.name === name)) fail(m, `${owner}: "${name}" is declared twice`)
+      fields.push({ name, type: readType(m.type, `${owner}.${name}`), optional: !!m.questionToken, doc: docOf(m) })
+    }
+    return fields
+  }
+
+  const readType = (n: tsModule.TypeNode, where: string): Type => {
+    if (ts.isParenthesizedTypeNode(n)) return readType(n.type, where)
+    switch (n.kind) {
+      case ts.SyntaxKind.StringKeyword: return { kind: "string" }
+      case ts.SyntaxKind.BooleanKeyword: return { kind: "boolean" }
+      case ts.SyntaxKind.VoidKeyword: fail(n, `${where}: void is the payload of an event or the result of a call, nothing else`); return VOID
+      case ts.SyntaxKind.NumberKeyword: fail(n, `${where}: say i32 or f64 — the native half must know what it reads`); return { kind: "f64" }
+      case ts.SyntaxKind.AnyKeyword:
+      case ts.SyntaxKind.UnknownKeyword:
+      case ts.SyntaxKind.ObjectKeyword: fail(n, `${where}: say Json for a value the generator passes through untyped`); return JSON_TYPE
+      case ts.SyntaxKind.UndefinedKeyword: fail(n, `${where}: an absent value is an optional member or argument (\`name?:\`), not undefined`); return JSON_TYPE
+    }
+    if (ts.isArrayTypeNode(n)) return { kind: "list", of: readType(n.elementType, where) }
+    if (ts.isTupleTypeNode(n)) {
+      // A pair or a triple is a type of every language a half is written in; a longer one is not
+      // (Kotlin has Pair and Triple), and its members deserve names by then.
+      if (n.elements.length < 2 || n.elements.length > 3) fail(n, `${where}: a tuple has two or three elements — say an interface for more`)
+      return { kind: "tuple", of: n.elements.map((e, i) => {
+        if (ts.isNamedTupleMember(e) || ts.isOptionalTypeNode(e) || ts.isRestTypeNode(e)) { fail(e, `${where}: a tuple's elements are plain types`); return JSON_TYPE }
+        return readType(e, `${where}[${i}]`)
+      }) }
+    }
+    if (ts.isTypeLiteralNode(n)) {
+      const index = n.members.length === 1 && ts.isIndexSignatureDeclaration(n.members[0]!) ? n.members[0] as tsModule.IndexSignatureDeclaration : undefined
+      if (index) {
+        const key = index.parameters[0]?.type
+        if (!key || key.kind !== ts.SyntaxKind.StringKeyword) fail(index, `${where}: a map's key is a string`)
+        return { kind: "map", of: readType(index.type, where) }
+      }
+      return { kind: "object", fields: readFields(n.members, where) }
+    }
+    if (ts.isLiteralTypeNode(n)) {
+      if (n.literal.kind === ts.SyntaxKind.NullKeyword) { fail(n, `${where}: null stands in a union — \`T | null\``); return JSON_TYPE }
+      if (ts.isStringLiteral(n.literal)) return { kind: "literals", values: [n.literal.text] }
+      fail(n, `${where}: a literal type is a string ("front"), not a number or a boolean`)
+      return JSON_TYPE
+    }
+    if (ts.isUnionTypeNode(n)) return readUnion(n, where)
+    if (ts.isTypeReferenceNode(n) && ts.isIdentifier(n.typeName)) return readReference(n, n.typeName.text, where)
+    fail(n, `${where}: \`${n.getText(sf)}\` is not a type a contract can carry`)
+    return JSON_TYPE
+  }
+
+  const readUnion = (n: tsModule.UnionTypeNode, where: string): Type => {
+    let nullable = false
+    const literals: string[] = []
+    const others: Type[] = []
+    // A nested union (parentheses) flattens into this one: its literals merge, its null is ours.
+    const absorb = (t: Type): void => {
+      if (t.kind === "literals") { for (const v of t.values) if (!literals.includes(v)) literals.push(v) }
+      else if (t.kind === "nullable") { nullable = true; absorb(t.of) }
+      else if (t.kind === "union") t.of.forEach(absorb)
+      else others.push(t)
+    }
+    for (const member of n.types) {
+      const m = ts.isParenthesizedTypeNode(member) ? member.type : member
+      if (ts.isLiteralTypeNode(m) && m.literal.kind === ts.SyntaxKind.NullKeyword) { nullable = true; continue }
+      absorb(readType(m, where))
+    }
+    if (literals.length > 0 && others.some(t => t.kind === "string")) fail(n, `${where}: string already holds every literal of this union`)
+    const members: Type[] = literals.length > 0 ? [{ kind: "literals", values: literals }, ...others] : others
+    if (members.length === 0) { fail(n, `${where}: null alone is not a type`); return JSON_TYPE }
+    const inner: Type = members.length === 1 ? members[0]! : { kind: "union", of: members }
+    return nullable ? { kind: "nullable", of: inner } : inner
+  }
+
+  const readReference = (n: tsModule.TypeReferenceNode, name: string, where: string): Type => {
+    const args = n.typeArguments ?? []
+    if (name === "Uint8Array") return { kind: "bytes" }
+    if (name === "Array" && args.length === 1) return { kind: "list", of: readType(args[0]!, where) }
+    if (name === "Record" && args.length === 2) {
+      if (args[0]!.kind !== ts.SyntaxKind.StringKeyword) fail(args[0]!, `${where}: a map's key is a string`)
+      return { kind: "map", of: readType(args[1]!, where) }
+    }
+    if (name === "Promise") { fail(n, `${where}: a promise is the result of a call, nothing else`); return JSON_TYPE }
+    if (args.length > 0) { fail(n, `${where}: \`${n.getText(sf)}\` — a contract names no generic type but Array and Record`); return JSON_TYPE }
+    if (name in VOCABULARY) {
+      if (!imported.has(name)) fail(n, `${where}: import ${name} from "${CONTRACT_MODULE}"`)
+      return { kind: VOCABULARY[name]! }
+    }
+    const iface = interfaces.get(name)
+    if (iface && markerOf(iface)) { fail(n, `${where}: ${name} is a channel, not a value`); return JSON_TYPE }
+    if (iface && isEventsInterface(name)) { fail(n, `${where}: ${name} is the events of a channel, not a value — name the payload's own type`); return JSON_TYPE }
+    if (iface || aliases.has(name)) return { kind: "ref", name }
+    fail(n, `${where}: ${name} is not declared in this contract`)
+    return JSON_TYPE
+  }
+
+  // ---- channels ------------------------------------------------------------------------------------
+  type Marker = { kind: Channel["kind"], node: tsModule.ExpressionWithTypeArguments }
+  const markerOf = (d: tsModule.InterfaceDeclaration): Marker | undefined => {
+    for (const clause of d.heritageClauses ?? []) {
+      for (const t of clause.types) {
+        const name = ts.isIdentifier(t.expression) ? t.expression.text : ""
+        if (name in MARKERS) return { kind: MARKERS[name]!, node: t }
+      }
+    }
+    return undefined
+  }
+
+  const isEventsInterface = (name: string): boolean => {
+    for (const d of interfaces.values()) {
+      const arg = markerOf(d)?.node.typeArguments?.[2]
+      if (arg && ts.isTypeReferenceNode(arg) && ts.isIdentifier(arg.typeName) && arg.typeName.text === name) return true
+    }
+    return false
+  }
+
+  /** The interface a marker argument names, as `what` ("params" / "events"). */
+  const markerInterface = (arg: tsModule.TypeNode | undefined, what: string, owner: string): tsModule.InterfaceDeclaration | undefined => {
+    if (!arg) return undefined
+    const name = ts.isTypeReferenceNode(arg) && ts.isIdentifier(arg.typeName) && !arg.typeArguments?.length ? arg.typeName.text : ""
+    const d = name ? interfaces.get(name) : undefined
+    if (!d) { fail(arg, `${owner}: the ${what} of a channel are an interface of this contract (got \`${arg.getText(sf)}\`)`); return undefined }
+    if (markerOf(d)) { fail(arg, `${owner}: ${name} is a channel, it cannot be the ${what} of one`); return undefined }
+    if (d.heritageClauses?.length) fail(d.name, `${name}: the ${what} of a channel extend nothing`)
+    return d
+  }
+
+  const readEvents = (d: tsModule.InterfaceDeclaration): Event[] => {
+    const events: Event[] = []
+    for (const m of d.members) {
+      const name = ts.isPropertySignature(m) && (ts.isIdentifier(m.name) || ts.isStringLiteral(m.name)) ? m.name.text : ""
+      if (!ts.isPropertySignature(m) || !m.type || !name) { fail(m, `${d.name.text}: an event is \`name: Payload\` — \`void\` for none. It is not written as a method`); continue }
+      if (m.questionToken) fail(m, `${d.name.text}.${name}: an event is not optional`)
+      if (events.some(e => e.name === name)) fail(m, `${d.name.text}: "${name}" is declared twice`)
+      const payload = m.type.kind === ts.SyntaxKind.VoidKeyword ? VOID : readType(m.type, `${d.name.text}.${name}`)
+      const { since, rejects } = tagsOf(m)
+      if (rejects.length) fail(m, `${d.name.text}.${name}: an event rejects nothing`)
+      events.push({ name, payload, since, doc: docOf(m), line: lineOf(m) })
+    }
+    return events
+  }
+
+  const readMethods = (d: tsModule.InterfaceDeclaration): Method[] => {
+    const methods: Method[] = []
+    for (const m of d.members) {
+      const owner = d.name.text
+      if (!ts.isMethodSignature(m) || !ts.isIdentifier(m.name)) { fail(m, `${owner}: a channel holds methods only — a value it sends is an event, a value it starts with is a param`); continue }
+      const name = m.name.text
+      const where = `${owner}.${name}`
+      if (methods.some(x => x.name === name)) fail(m, `${owner}: "${name}" is declared twice (a contract has no overloads)`)
+      if (KEYWORDS.has(name) || name.startsWith("_")) fail(m.name, `${where}: "${name}" is a keyword of a language the contract is generated to — pick another name`)
+      else if (TAKEN.has(name)) fail(m.name, `${where}: "${name}" is a member of every wrapper already — pick another name`)
+      if (m.questionToken) fail(m, `${where}: a method is not optional — a method added later is tagged @since`)
+      if (m.typeParameters?.length) fail(m, `${where}: a method is not generic`)
+
+      const args: Arg[] = []
+      for (const p of m.parameters) {
+        if (!ts.isIdentifier(p.name) || !p.type || p.dotDotDotToken) { fail(p, `${where}: an argument is \`name: Type\` or \`name?: Type\``); continue }
+        const optional = !!p.questionToken
+        if (KEYWORDS.has(p.name.text)) fail(p.name, `${where}: "${p.name.text}" is a keyword of a language the contract is generated to — pick another name`)
+        if (!optional && args.some(a => a.optional)) fail(p, `${where}: "${p.name.text}" follows an optional argument — optional ones come last`)
+        args.push({ name: p.name.text, type: readType(p.type, `${where}(${p.name.text})`), optional })
+      }
+
+      let result: Type = VOID
+      const r = m.type
+      const promised = r && ts.isTypeReferenceNode(r) && ts.isIdentifier(r.typeName) && r.typeName.text === "Promise" && r.typeArguments?.length === 1 ? r.typeArguments[0]! : undefined
+      if (!promised) fail(m, `${where}: a call crosses to the host and back — it returns Promise<…>`)
+      else if (promised.kind !== ts.SyntaxKind.VoidKeyword) result = readType(promised, `${where}()`)
+
+      methods.push({ name, args, result, ...tagsOf(m), doc: docOf(m), line: lineOf(m) })
+    }
+    return methods
+  }
+
+  // ---- pass 2: the declarations ---------------------------------------------------------------------
+  const channels: Channel[] = []
+  const decls: Decl[] = []
+  const paramsParts = new Set<string>()
+  /** An events interface is not a struct (a payload may be void): it lives in its channel only. */
+  const eventsParts = new Set<string>()
+
+  for (const d of interfaces.values()) {
+    const marker = markerOf(d)
+    if (!marker) continue
+    const iface = d.name.text
+    const heritage = (d.heritageClauses ?? []).flatMap(c => [...c.types])
+    if (heritage.length > 1) fail(d.name, `${iface}: a channel extends its marker and nothing else`)
+    const [nameArg, paramsArg, eventsArg, ...rest] = marker.node.typeArguments ?? []
+    if (rest.length) fail(marker.node, `${iface}: the marker takes a name, the params, the events`)
+    const markerName = ts.isIdentifier(marker.node.expression) ? marker.node.expression.text : ""
+    if (!imported.has(markerName)) fail(marker.node, `${iface}: import ${markerName} from "${CONTRACT_MODULE}"`)
+
+    let name = ""
+    if (nameArg && ts.isLiteralTypeNode(nameArg) && ts.isStringLiteral(nameArg.literal)) name = nameArg.literal.text
+    else fail(marker.node, `${iface}: the marker's first argument is the channel's name, a string literal — what the halves register under`)
+    if (name && !/^[a-z][A-Za-z0-9]*(\.[a-z][A-Za-z0-9]*)*$/.test(name)) fail(nameArg!, `${iface}: "${name}" is not a channel name (camelCase, a vendor prefix before a dot: "acme.bluetooth")`)
+    if (name && channels.some(c => c.name === name && c.kind === marker.kind)) fail(nameArg!, `${iface}: the ${marker.kind} "${name}" is declared twice`)
+
+    const paramsDecl = markerInterface(paramsArg, "params", iface)
+    const eventsDecl = markerInterface(eventsArg, "events", iface)
+    if (paramsDecl) paramsParts.add(paramsDecl.name.text)
+    if (eventsDecl) eventsParts.add(eventsDecl.name.text)
+
+    // A view is mounted by the host whatever the app passed: params it could not read have no one to
+    // reject to, so every one of them can be left out.
+    for (const m of paramsDecl?.members ?? []) {
+      if (ts.isPropertySignature(m) && !m.questionToken) fail(m, `${paramsDecl!.name.text}: a param is optional (\`${m.name.getText(sf)}?:\`) — the half falls back on its default`)
+    }
+    const events = eventsDecl ? readEvents(eventsDecl) : []
+    const methods = readMethods(d)
+    const { since, rejects } = tagsOf(d)
+    if (since !== 1 || rejects.length) fail(d.name, `${iface}: @since and @rejects tag a method or an event, not the channel`)
+    channels.push({
+      kind: marker.kind, name, iface,
+      params: paramsDecl ? readFields(paramsDecl.members, paramsDecl.name.text) : [],
+      ...(paramsDecl ? { paramsType: paramsDecl.name.text } : {}),
+      ...(eventsDecl ? { eventsType: eventsDecl.name.text } : {}),
+      events, methods,
+      version: Math.max(1, ...methods.map(m => m.since), ...events.map(e => e.since)),
+      doc: docOf(d), line: lineOf(d),
+    })
+  }
+
+  for (const d of interfaces.values()) {
+    if (markerOf(d)) continue
+    const name = d.name.text
+    if (eventsParts.has(name)) continue
+    if (d.heritageClauses?.length && !paramsParts.has(name)) fail(d.name, `${name}: a struct extends nothing — repeat the members or name the other struct as a member`)
+    // A params interface is read with its channel AND stays a struct a member may name.
+    decls.push({ kind: "struct", name, fields: readFields(d.members, name), doc: docOf(d), line: lineOf(d) })
+  }
+  for (const a of aliases.values()) {
+    decls.push({ kind: "alias", name: a.name.text, type: readType(a.type, a.name.text), doc: docOf(a), line: lineOf(a) })
+  }
+
+  if (channels.length === 0 && problems.length === 0) {
+    problems.push({ line: 1, message: "a contract declares a channel: an interface that extends View<…> or Service<…>" })
+  }
+
+  if (problems.length) {
+    // A params interface is read twice (its channel, its struct): one report per finding.
+    const seen = new Set<string>()
+    const unique = problems.filter(p => { const k = `${p.line}:${p.message}`; if (seen.has(k)) return false; seen.add(k); return true })
+    throw new ContractError(file, unique.sort((a, b) => a.line - b.line))
+  }
+  return { file, channels, decls: decls.sort((a, b) => a.line - b.line) }
+}