Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

16.8 KB
Raw Blame
/**
 * Do the interfaces a package was written against still fit this platform?
 *
 * A comparison needs two declarations. Looking both sides up in the platform's own table
 * compares a declaration with itself and can never fail, so here each side brings its own:
 * the CONSUMER's is the table the package carries — a plugin's generated `ifaces.json`; for
 * a workflow, the slice of the harness's table it was written against, kept in its folder
 * (../workflows/harness-types.ts) — and the PLATFORM's is this generation's. Nothing in
 * this module judges assignability itself: each table is rendered as a self-contained
 * `.d.ts`, the questions become assignments in a third file, and the TypeScript compiler
 * answers them —
 *
 *   requires  the platform's interface must be assignable to the consumer's view of it;
 *   provides  the consumer's view must be assignable to what the platform asks for.
 *
 * Two rules keep a pass meaningful. The consumer's table is never substituted: an
 * interface it does not carry is reported as uncompared, never answered from the platform's
 * entry. And rendering is lossless or it refuses: an expression this module cannot write as
 * TypeScript is reported by name, never widened to `unknown`.
 */
import os from "node:os";
import path from "node:path";
import type { IfaceDecl, IfaceTable, Manifest, Sig, TypeExpr } from "@adelie/core/kernel";
import type { TypeScript } from "./typescript.js";

export class IfaceRenderError extends Error {}

/** `<package>#<Export>` → its package; null for a reference with no package part. */
export function packageOf(key: string): string | null {
  const at = key.indexOf("#");
  return at <= 0 ? null : key.slice(0, at);
}

// ---- table → .d.ts ------------------------------------------------------------------

const WORDS = new Set([
  ..."string number boolean bigint symbol object null undefined unknown never true false Date".split(
    " ",
  ),
]);
const INFIX = new Set(["|", "&"]);
/** Opaque identities that name a type of TypeScript's own library (`lib#<Name>` in the table). */
const LIB_TYPES = new Set(["lib#Uint8Array"]);
const OPERATORS = new Set(["[]", "|", "&", "?", "=>", ":", "=", "@", "===", "keyof", "instanceof"]);

/** An arktype string expression is written as TypeScript already, for the subset checked here. */
function stringExpression(expr: string, where: string): string {
  const rest = expr
    .replace(/'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g, " ")
    .replace(/-?\b\d+(?:\.\d+)?\b/g, " ")
    .replace(/[A-Za-z_][A-Za-z0-9_]*/g, (word) => (WORDS.has(word) ? " " : word));
  if (!/^[\s|&()[\]]*$/.test(rest)) {
    throw new IfaceRenderError(
      `${where}: '${expr}' is not an expression this check can write as TypeScript`,
    );
  }
  return `(${expr})`;
}

/** Whether a parameter's type lets the argument be left out. */
function admitsUndefined(e: TypeExpr): boolean {
  if ("maybe" in e) return true;
  if ("oneOf" in e) return e.oneOf.some(admitsUndefined);
  if (!("data" in e)) return false;
  const inData = (d: unknown): boolean =>
    typeof d === "string"
      ? d.split("|").some((part) => part.trim() === "undefined")
      : Array.isArray(d) && d.length === 3 && d[1] === "|" && (inData(d[0]) || inData(d[2]));
  return inData(e.data);
}

const property = (name: string) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));

class Renderer {
  private readonly names = new Map<string, string>();
  private readonly taken = new Set<string>();
  private readonly out: string[] = [];
  private readonly done = new Set<string>();

  constructor(private readonly table: IfaceTable) {}

  /**
   * The identifier a table key is declared under: its export name (`…#WorkflowHost` →
   * `WorkflowHost`), numbered on a clash — so the text reads as a declaration file an author
   * can write against, and a diagnostic names the type the way its source does.
   */
  ident(key: string): string {
    let name = this.names.get(key);
    if (name !== undefined) return name;
    const base = key
      .slice(key.indexOf("#") + 1)
      .replace(/[^A-Za-z0-9]+/g, "_")
      .replace(/^_+|_+$/g, "")
      .replace(/^(\d)/, "_$1");
    name = base;
    for (let n = 2; this.taken.has(name); n++) name = `${base}_${n}`;
    this.taken.add(name);
    this.names.set(key, name);
    return name;
  }

  /** What was rendered, as a table of its own: the declared interfaces and all they reach. */
  readonly slice: IfaceTable = { ifaces: {}, types: {} };

  iface(key: string): string {
    const name = this.ident(`iface ${key}`);
    if (this.done.has(name)) return name;
    this.done.add(name);
    const decl = this.table.ifaces[key];
    if (decl === undefined) throw new IfaceRenderError(`'${key}' is not in the table`);
    this.slice.ifaces[key] = decl;
    this.out.push(this.interfaceText(name, key, decl));
    return name;
  }

  text(): string {
    return [
      // Branded by a plain, string-keyed property — never `unique symbol`. Each side is its
      // own file, and a `unique symbol` declared in each is two different symbols, so the
      // same opaque rendered on both sides would not be assignable to itself. The name is
      // the identity (core/src/kernel/markers.ts), which is what the table records.
      "type Opaque<Name extends string> = { readonly __opaque: Name };",
      ...this.out,
    ].join("\n");
  }

  private namedType(key: string): string {
    const name = this.ident(`type ${key}`);
    if (this.done.has(name)) return name;
    this.done.add(name);
    const def = this.table.types[key];
    if (def === undefined)
      throw new IfaceRenderError(`type '${key}' is referenced but not in the table`);
    this.slice.types[key] = def;
    // Reserve the slot first: a recursive type refers to itself by this name.
    const at = this.out.push("") - 1;
    this.out[at] = `export type ${name} = ${this.data(def, key)};`;
    return name;
  }

  private interfaceText(name: string, key: string, decl: IfaceDecl): string {
    // Members are PROPERTIES of function type: under strictFunctionTypes their parameters
    // are contravariant, the rule the module tree states. Method shorthand is bivariant
    // and would let a narrowed parameter through.
    const methods = Object.entries(decl.methods).map(
      ([m, sig]) => `  ${property(m)}: ${this.sig(sig, `${key}.${m}`)};`,
    );
    const fields = Object.entries(decl.fields ?? {}).map(
      ([f, e]) => `  ${property(f)}${"maybe" in e ? "?" : ""}: ${this.expr(e, `${key}.${f}`)};`,
    );
    return `export interface ${name} {\n${[...methods, ...fields].join("\n")}\n}`;
  }

  private sig(sig: Sig, where: string): string {
    // The table has no "optional parameter", only a type that admits undefined; trailing
    // ones are written back as optional, or `f()` would not type-check against `f(a?: T)`.
    let required = sig.params.length;
    while (required > 0 && admitsUndefined(sig.params[required - 1]!)) required--;
    const params = sig.params.map(
      (p, i) => `a${i}${i >= required ? "?" : ""}: ${this.expr(p, where)}`,
    );
    return `(${params.join(", ")}) => ${this.expr(sig.returns, where)}`;
  }

  private expr(e: TypeExpr, where: string): string {
    if ("data" in e) return this.data(e.data, where);
    if ("iface" in e) return this.iface(e.iface);
    if ("fn" in e) return `(${this.sig(e.fn, where)})`;
    if ("promise" in e) return `Promise<${this.expr(e.promise, where)}>`;
    if ("stream" in e)
      return e.returns === undefined
        ? `AsyncIterable<${this.expr(e.stream, where)}>`
        : `AsyncGenerator<${this.expr(e.stream, where)}, ${this.expr(e.returns, where)}>`;
    if ("void" in e) return "void";
    if ("array" in e) return `Array<${this.expr(e.array, where)}>`;
    if ("object" in e) {
      const optional = new Set(e.optional ?? []);
      const members = Object.entries(e.object).map(
        ([k, v]) => `${property(k)}${optional.has(k) ? "?" : ""}: ${this.expr(v, where)}`,
      );
      return `{ ${members.join("; ")} }`;
    }
    if ("maybe" in e) return `(${this.expr(e.maybe, where)} | null | undefined)`;
    if ("oneOf" in e) return `(${e.oneOf.map((x) => this.expr(x, where)).join(" | ")})`;
    // A type of the language's own library is the same type in every program: it is written
    // as itself, where a host-declared opaque is a brand nobody else can construct.
    if ("opaque" in e && LIB_TYPES.has(e.opaque)) return e.opaque.slice("lib#".length);
    if ("opaque" in e) return `Opaque<${JSON.stringify(e.opaque)}>`;
    throw new IfaceRenderError(
      `${where}: ${JSON.stringify(e).slice(0, 120)} has no TypeScript rendering`,
    );
  }

  /** An arktype definition (string expression, tuple expression or object form). */
  private data(def: unknown, where: string): string {
    if (typeof def === "string") return stringExpression(def, where);
    if (Array.isArray(def)) {
      if (def.length === 2 && def[1] === "[]") return `Array<${this.data(def[0], where)}>`;
      if (def.length === 3 && typeof def[1] === "string" && INFIX.has(def[1])) {
        return `(${this.data(def[0], where)} ${def[1]} ${this.data(def[2], where)})`;
      }
      if (!def.some((x) => typeof x === "string" && OPERATORS.has(x))) {
        return `[${def.map((x) => this.data(x, where)).join(", ")}]`;
      }
    } else if (def !== null && typeof def === "object") {
      const record = def as Record<string, unknown>;
      if (typeof record["$ref"] === "string") return this.namedType(record["$ref"]);
      const members = Object.entries(record).map(([k, v]) => {
        if (k === "[string]") return `[key: string]: ${this.data(v, where)}`;
        if (k === "+" || k === "..." || k.startsWith("[")) {
          throw new IfaceRenderError(`${where}: object key '${k}' has no TypeScript rendering`);
        }
        const optional = k.endsWith("?");
        return `${property(optional ? k.slice(0, -1) : k)}${optional ? "?" : ""}: ${this.data(v, where)}`;
      });
      return `{ ${members.join("; ")} }`;
    }
    throw new IfaceRenderError(
      `${where}: ${JSON.stringify(def).slice(0, 120)} has no TypeScript rendering`,
    );
  }
}

/**
 * A self-contained `.d.ts` declaring `keys` (and everything they reach) out of `table`,
 * with the part of the table it was made from.
 */
export function renderDts(
  table: IfaceTable,
  keys: readonly string[],
): { text: string; names: Map<string, string>; slice: IfaceTable } {
  const renderer = new Renderer(table);
  const names = new Map(keys.map((key) => [key, renderer.iface(key)]));
  return { text: renderer.text(), names, slice: renderer.slice };
}

// ---- the questions --------------------------------------------------------------------

export interface IfaceQuestion {
  /** The module asking, for the message. */
  module: string;
  alias: string;
  direction: "requires" | "provides";
  /** `<package>#<Export>`. */
  key: string;
}

/** The interfaces manifests name with a package part, as questions for the compiler. */
export function ifaceQuestions(manifests: readonly Manifest[]): IfaceQuestion[] {
  const out: IfaceQuestion[] = [];
  for (const m of manifests) {
    for (const [alias, need] of Object.entries(m.requires)) {
      if (packageOf(need.iface) === null) continue;
      out.push({ module: m.name, alias, direction: "requires", key: need.iface });
    }
    for (const [alias, ref] of Object.entries(m.provides)) {
      if (packageOf(ref) === null) continue;
      out.push({ module: m.name, alias, direction: "provides", key: ref });
    }
  }
  return out;
}

export interface IfaceCheckResult {
  /** Why the package does not fit; empty when every comparison passed. */
  problems: string[];
  /** Interfaces that could not be compared: the consumer's table carries no copy of them. */
  uncompared: string[];
}

/**
 * Answers every question with the compiler. A question about an interface this platform
 * does not declare is not one for here (the tree check names it). One the consumer's table
 * does not carry cannot be compared, and is never answered from the platform's own entry:
 * it is reported as `uncompared`, and whether that is a failure is the caller's rule.
 */
export function checkIfaces(
  ts: TypeScript,
  platform: IfaceTable,
  consumer: IfaceTable,
  questions: readonly IfaceQuestion[],
): IfaceCheckResult {
  const problems: string[] = [];
  const uncompared: string[] = [];
  const label = (q: IfaceQuestion) => `${q.module}: ${q.direction}.${q.alias} '${q.key}'`;
  const base = path.join(os.tmpdir(), "penguin-iface-check");
  const files = new Map<string, string>();
  const asked = questions.filter((q) => {
    // Either side missing its copy means there is nothing to compare — and it is recorded,
    // never answered from the other side's entry. Both are counted, so the log's tally is
    // the number of questions that went unanswered rather than half of it.
    if (platform.ifaces[q.key] === undefined || consumer.ifaces[q.key] === undefined) {
      uncompared.push(label(q));
      return false;
    }
    return true;
  });
  if (asked.length === 0) return { problems, uncompared };

  const keys = [...new Set(asked.map((q) => q.key))];
  let ours: ReturnType<typeof renderDts>;
  let theirs: ReturnType<typeof renderDts>;
  try {
    ours = renderDts(platform, keys);
  } catch (err) {
    // The platform's own table: a rendering fault here is ours, and the caller hears it.
    problems.push(`interface check: ${err instanceof Error ? err.message : String(err)}`);
    return { problems, uncompared };
  }
  try {
    theirs = renderDts(consumer, keys);
  } catch (err) {
    // The package's table. A platform must not take a package away from a machine for
    // something the package did not do (plugin/loader.ts), and an expression this renderer
    // cannot write is exactly that: not compared, said out loud, never a refusal.
    const why = err instanceof Error ? err.message : String(err);
    for (const q of asked) uncompared.push(`${label(q)} (${why})`);
    return { problems, uncompared };
  }
  files.set(path.join(base, "platform.d.ts"), ours.text);
  files.set(path.join(base, "consumer.d.ts"), theirs.text);
  const lines = [
    `import type * as P from "./platform.js";`,
    `import type * as C from "./consumer.js";`,
    // One question per line: the diagnostic's line number names the question.
    ...asked.map((q, n) => {
      const [from, to] =
        q.direction === "requires"
          ? [`P.${ours.names.get(q.key)}`, `C.${theirs.names.get(q.key)}`]
          : [`C.${theirs.names.get(q.key)}`, `P.${ours.names.get(q.key)}`];
      return `declare const q${n}: ${from}; export const a${n}: ${to} = q${n};`;
    }),
  ];

  const checkFile = path.join(base, "check.ts");
  files.set(checkFile, lines.join("\n") + "\n");
  const firstQuestionLine = lines.length - asked.length;
  const options: import("typescript").CompilerOptions = {
    strict: true,
    noEmit: true,
    types: [],
    target: ts.ScriptTarget.ES2022,
    // The language's own library without the DOM: the rendered tables use Promise, Array,
    // AsyncIterable and the typed arrays, and parsing lib.dom.d.ts on every check is the
    // largest single cost of one.
    lib: ["lib.es2022.d.ts"],
    module: ts.ModuleKind.NodeNext,
    moduleResolution: ts.ModuleResolutionKind.NodeNext,
  };
  const host = ts.createCompilerHost(options);
  const { fileExists, readFile, getSourceFile } = host;
  const virtual = (file: string) => files.get(path.resolve(file));
  // The files exist only here; the resolver asks about their directory before it asks about them.
  const directoryExists = host.directoryExists;
  host.directoryExists = (dir) =>
    path.resolve(dir) === base || (directoryExists?.call(host, dir) ?? true);
  host.fileExists = (file) => virtual(file) !== undefined || fileExists.call(host, file);
  host.readFile = (file) => virtual(file) ?? readFile.call(host, file);
  host.getSourceFile = (file, languageVersion, ...rest) => {
    const text = virtual(file);
    return text === undefined
      ? getSourceFile.call(host, file, languageVersion, ...rest)
      : ts.createSourceFile(file, text, languageVersion, true);
  };
  const program = ts.createProgram([checkFile], options, host);
  for (const d of ts.getPreEmitDiagnostics(program)) {
    const text = ts
      .flattenDiagnosticMessageText(d.messageText, "\n    ")
      .replace(/import\("[^"]*"(?:, \{[^}]*\{[^}]*\} \})?\)\./g, "");
    const line =
      d.file && d.start !== undefined ? d.file.getLineAndCharacterOfPosition(d.start).line : -1;
    const q =
      d.file && path.resolve(d.file.fileName) === checkFile
        ? asked[line - firstQuestionLine]
        : undefined;
    if (q === undefined) {
      problems.push(`interface check: TS${d.code} ${text}`);
      continue;
    }
    problems.push(
      `${label(q)}: ${
        q.direction === "requires"
          ? "this platform's interface does not fit the version the package was written against"
          : "the version the package was written against does not fit what this platform asks for"
      }\n    TS${d.code} ${text}`,
    );
  }
  return { problems, uncompared };
}