@meantjs/cli 0.0.0-bootstrap → 0.0.0-stage

package/lib/index.d.ts

@@ -1,521 +0,0 @@
-/**
- * The library surface of `@meantjs/cli`: data in, data out.
- *
- * Every type here describes what the wasm compiler actually serializes. In
- * particular a {@link Diagnostic} carries only `code` and `message`
- * unconditionally — every other field is genuinely optional, because the same
- * item algebra carries both compile diagnostics (which populate `phase` and
- * `severity`) and validation violations (which populate `path` and never
- * those two).
- */
-
-/**
- * Candid input. Either self-contained text, or a bundle naming its entry.
- *
- * `{ source }` and `{ entry, files }` are mutually exclusive, and no other key
- * is accepted — a request carrying one is refused with `invalid_request`.
- */
-export type Sources =
-  string | { source: string } | { entry: string; files: Record<string, string> };
-
-/**
- * A logical source location. Every field is optional: an *approximate* span
- * names the source without offsets, and a span may name offsets without a
- * source.
- */
-export interface SourceSpan {
-  source_name?: string;
-  start_byte?: number;
-  end_byte?: number;
-}
-
-/** A secondary location attached to a diagnostic. */
-export interface RelatedLocation {
-  message: string;
-  span?: SourceSpan;
-}
-
-/** Which bound refused, the ceiling it enforces, and what was observed. */
-export interface ResourceLimitInfo {
-  resource: string;
-  limit: number;
-  observed: number;
-}
-
-/**
- * One failure item.
- *
- * `phase` is deliberately `string` rather than a union: the compiler's own
- * phases are joined by values this package writes itself, so any closed set
- * would be wrong today and wronger later. Compare `code`, which is the stable
- * identifier meant for programmatic use.
- */
-export interface Diagnostic {
-  code: string;
-  message: string;
-  phase?: string;
-  severity?: string;
-  path?: string;
-  span?: SourceSpan;
-  related?: RelatedLocation[];
-  notes?: string[];
-  resource_limit?: ResourceLimitInfo;
-}
-
-/**
- * The failure document, identical to what the native `meant` CLI
- * prints. Nothing is thrown for a data error.
- */
-export interface Failure {
-  ok: false;
-  diagnostics: Diagnostic[];
-}
-
-/** One `[container, id, name]` field-label triple. */
-export type FieldNameTriple = [container: number, id: number, name: string];
-
-/**
- * A one-document `ContractEnvelope`: the canonical contract plus its
- * extensions map. `contract` is typed `unknown` on purpose — it is handed
- * whole to `schemaFromContract`, which itself accepts `unknown`, and pinning
- * its shape here would duplicate a model that versions independently.
- */
-export interface ContractEnvelope {
-  contract: unknown;
-  extensions: {
-    "org.candid-core.field-names/v1"?: FieldNameTriple[];
-    [extension: string]: unknown;
-  };
-}
-
-/**
- * One declaration or method a module leaves out.
- */
-export interface Omission {
-  /** A named declaration, or a method of the actor's service. */
-  kind: "declaration" | "method";
-  /** The declaration or method name, as the Candid source spells it. */
-  name: string;
-  /**
-   * Why, from a closed set: `reserved_field_name` (a field or arm named
-   * like the `_N_` id rendering), `ambiguous_variant_arm` (an arm whose
-   * payload is a declared `opt` of an uninhabited type),
-   * `reserved_export_name` (a declaration named `actor` or `Actor`),
-   * `invalid_declaration_name` (a name that is not identifier-shaped;
-   * Contract documents only), or `references_omitted` (it references the
-   * omitted declaration named by `via`).
-   */
-  reason:
-    | "reserved_field_name"
-    | "ambiguous_variant_arm"
-    | "reserved_export_name"
-    | "invalid_declaration_name"
-    | "references_omitted";
-  /** For `references_omitted` only: the omitted declaration referenced. */
-  via?: string;
-}
-
-/**
- * A successful module generation. A module that had to leave something out
- * is still a success: everything it emits is exactly what it would be
- * without the omitted declarations, and `omitted` lists what is missing.
- */
-export interface ModuleSuccess {
-  ok: true;
-  /**
-   * The generated TypeScript. With omissions, its header lists them, one
-   * `// Omitted:` line each; with none, the text is unchanged.
-   */
-  module: string;
-  /**
-   * What the module leaves out: a declaration no module can
-   * represent, together with every declaration and actor method that
-   * references it — through nested `func` and `service` types too, up to the
-   * containing declaration. Only the actor drops individual methods, from
-   * both `actor` and `Actor`. Declarations first, then methods, each sorted
-   * by name; empty, never absent, when nothing is omitted.
-   * `schemaFromContract` reports the same list for the same Contract.
-   */
-  omitted: Omission[];
-}
-
-/**
- * Initialize the embedded wasm module once; repeated calls return the same
- * promise. Node needs no argument. A browser may also pass nothing, or supply
- * its own `BufferSource`, `URL` or `Response`.
- *
- * The parameter is typed `unknown` deliberately: `BufferSource`, `URL` and
- * `Response` are DOM types, and naming them here would break every consumer
- * compiling without the DOM lib — which is most Node consumers of a CLI.
- */
-export function init(input?: unknown): Promise<void>;
-
-/**
- * Compile Candid sources into a one-document `ContractEnvelope` carrying the
- * `org.candid-core.field-names/v1` extension — exactly the document
- * `meant compile <path> --envelope` emits, ready for
- * `schemaFromContract`.
- *
- * Discriminate on the envelope, not on `ok`: success carries no `ok` key.
- *
- * @example
- * const result = await didToContract("service : { ping : () -> (); }");
- * if ("contract" in result) {
- *   const built = schemaFromContract(result);
- * } else {
- *   for (const issue of result.diagnostics) console.error(issue.code, issue.message);
- * }
- */
-export function didToContract(sources: Sources): Promise<ContractEnvelope | Failure>;
-
-/**
- * Generate the `@meantjs/schema` TypeScript module for Candid sources,
- * byte-identical to what the Rust-native generator emits, with the list of
- * declarations and methods it had to leave out.
- *
- * @example
- * const result = await didToModule("service : { ping : () -> (); }");
- * if (result.ok) {
- *   for (const entry of result.omitted) console.warn("omitted", entry.name, entry.reason);
- *   await writeFile("./service.ts", result.module);
- * }
- */
-export function didToModule(sources: Sources): Promise<ModuleSuccess | Failure>;
-
-/** Where a SourceInfo entry came from: a declaration, or the actor. */
-export type SourceOrigin =
-  { kind: "declaration"; source: string; name: string } | { kind: "actor"; source: string };
-
-/**
- * One argument value of a doc attribute. A number keeps the text written
- * (`"8"`, `"-1"`, `"0.25"`), never a binary float.
- */
-export type DocValue =
-  | { kind: "text"; value: string }
-  | { kind: "number"; value: string }
-  | { kind: "bool"; value: boolean }
-  | { kind: "ident"; value: string }
-  | { kind: "call"; name: string; args: DocValue[] }
-  | { kind: "list"; items: DocValue[] }
-  | { kind: "record"; fields: DocArgument[] };
-
-/** `key = value`. Keys are unique within one argument list or record. */
-export interface DocArgument {
-  key: string;
-  value: DocValue;
-}
-
-/** One `@name(…)` doc line, or one that continues over several lines. */
-export interface DocAttribute {
-  /** Lowercase segments joined by `.`: `amount`, `ui.hidden`. */
-  name: string;
-  /** Index of the attribute's first line in the item's docs, from 0. */
-  doc_line: number;
-  /** In the order written; empty for `@name` and `@name()`. */
-  args: DocArgument[];
-}
-
-/** A documented item: its prose lines and its attributes. */
-export interface DocItem {
-  kind: "actor" | "declaration" | "field" | "method";
-  origin: SourceOrigin;
-  /**
-   * `actor`, `type:<Name>`, or the occurrence path SourceInfo records for a
-   * method or field (`actor.methods[2]`, `type:Tokens.fields[0]`,
-   * `actor.methods[1].function.args[0].type.fields[0]`).
-   */
-  path: string;
-  /** The declaration or method name, or a field's named label. */
-  name?: string;
-  /** The doc lines that are not attributes, normalized, in order. */
-  prose: string[];
-  attributes: DocAttribute[];
-}
-
-/** Doc attributes v1 of one compilation: every item with a doc line. */
-export interface DocAttributes {
-  doc_attributes_version: 1;
-  /** The actor, then declarations, methods and fields, in SourceInfo order. */
-  items: DocItem[];
-}
-
-/** A successful `didToDocAttributes`. */
-export interface DocAttributesSuccess {
-  ok: true;
-  /** The canonical Contract, as in `didToContract`'s envelope. */
-  contract: unknown;
-  /**
-   * The SourceInfo sidecar as `meant compile <path>` prints it, typed
-   * `unknown` for the same reason as `contract`: it versions independently.
-   */
-  source_info: unknown;
-  doc_attributes: DocAttributes;
-}
-
-/**
- * Compile Candid sources and read the `@name(key = value, …)` attributes in
- * their doc comments. The compiler gives no attribute a meaning; the reading
- * tool decides which names it knows. A malformed attribute fails the call
- * with `doc_attribute_malformed` or `doc_attribute_duplicate_key`, whose
- * `path` names the item. Comments never change `contract_id` or
- * `interface_id`.
- *
- * @example
- * const result = await didToDocAttributes(serviceDid);
- * if (result.ok) {
- *   for (const item of result.doc_attributes.items)
- *     for (const attribute of item.attributes) console.log(item.path, attribute.name);
- * }
- */
-export function didToDocAttributes(sources: Sources): Promise<DocAttributesSuccess | Failure>;
-
-/** The identities of one compiled interface. */
-export interface Identities {
-  /** The Contract identity: the whole canonical graph, declarations included. */
-  contract_id: string;
-  /**
-   * The interface identity: only what the service reaches. Equal identities
-   * mean an unchanged interface.
-   */
-  interface_id: string;
-}
-
-/** A successful projection. */
-export interface ProjectionSuccess {
-  ok: true;
-  /**
-   * The projected `.did`: the methods named and every declaration they
-   * reach, as one self-contained file. Declaration names, doc comments and
-   * argument names are kept; a service class's init arguments are not.
-   * Methods are printed in name order (code point), record fields and
-   * variant arms in label-id order, declarations in source order (the
-   * entry's first, then each imported source's).
-   */
-  did: string;
-  /** The methods the projection holds, in name order (code point). */
-  methods: string[];
-  /** The identities of the sources projected. */
-  input: Identities;
-  /** The identities of the projection. */
-  projection: Identities;
-}
-
-/**
- * Project Candid sources onto the methods named: a self-contained `.did`
- * holding exactly those methods and every declaration they reach. The same
- * sources and the same set of names give the same bytes, in any order.
- *
- * A failure is `unknown_method` (one per distinct name the service lacks,
- * in the order first named; the failure's first diagnostic lists the
- * service's methods in its `notes`, once), `empty_method_list`,
- * `no_service`, `resource_limit_exceeded`, or the compiler's own
- * diagnostics. `resource_limit_exceeded` names its bound in
- * `resource_limit.resource`: `projection_bytes` when the projection would
- * pass the 1 MiB the compiler accepts in one source (`observed` is where
- * printing stopped), or `projection_diagnostic_bytes` when the
- * unknown-method diagnostics would pass 4 MiB, each counted as the failure
- * writes it (the list of methods aside), the names left being counted in
- * that diagnostic instead of reported.
- *
- * @example
- * const result = await projectDid(ledgerDid, ["icrc1_balance_of", "icrc1_transfer"]);
- * if (result.ok) await writeFile("./ledger.did", result.did);
- */
-export function projectDid(
-  sources: Sources,
-  methods: readonly string[],
-): Promise<ProjectionSuccess | Failure>;
-
-/**
- * One finding of a compatibility check.
- *
- * - `method_missing` (error): the live service has no method of that name.
- * - `mode_changed` (error): the method's mode differs (`query`,
- *   `composite_query`, `update` or `oneway`).
- * - `method_incompatible` (error): the live method's type is not a subtype
- *   of the written one; `path` says where.
- * - `special_opt_rule` (warning): the types are compatible only because
- *   Candid reads a mismatch under an `opt` as `null`, so a value at `path`
- *   decodes as `null`. One is reported at every such path along which no
- *   pair of types repeats: a shared type under each path that reaches it,
- *   and a recursive type up to where a path comes back round to a pair it
- *   already passed through.
- * - `resource_limit_exceeded`: as an error, the check of this method
- *   stopped at one of its bounds (`resource_limit.resource` is
- *   `check_depth` or `check_steps`; a step is one unit of work done, such
- *   as a pair of types visited or a field examined) and fails closed. As a
- *   warning (`check_warnings`), the method has more `special_opt_rule`
- *   warnings than the 1,000 reported; its verdict is complete and stands.
- *   As an error naming `check_total_steps` or `check_total_warnings`, the
- *   check as a whole reached its bound of 10,000,000 steps or 10,000
- *   `special_opt_rule` warnings: methods are checked in name order, and
- *   the method at which the bound was reached and every method after it
- *   get this one diagnostic and nothing else. As an error naming
- *   `check_output_bytes`, the reported diagnostics reached their bound of
- *   4 MiB, each counted as the response writes it: this one ends the list,
- *   names no `method`, and counts in `unreported_methods` the methods it
- *   stands for, the last written ones in name order, from the one whose
- *   diagnostics did not fit; they fail closed. Below these bounds a
- *   method's findings do not depend on the other methods.
- */
-export interface CompatibilityDiagnostic {
-  code:
-    | "method_missing"
-    | "mode_changed"
-    | "method_incompatible"
-    | "special_opt_rule"
-    | "resource_limit_exceeded";
-  severity: "error" | "warning";
-  /**
-   * The written method the finding is about. Absent only on the
-   * `check_output_bytes` diagnostic that ends a check, which counts methods
-   * in `unreported_methods` instead.
-   */
-  method?: string;
-  /**
-   * Where in the method's type: `$args[i]` or `$results[i]`, then `.name`
-   * (or `["name"]`, or `[id]` for a numeric label) per record field or
-   * variant arm, `[*]` per vec element, `?` per opt content, and
-   * `::args[i]`, `::results[i]` or `::name` into a func or service type.
-   * Absent for `method_missing`, `mode_changed` and
-   * `resource_limit_exceeded`.
-   */
-  path?: string;
-  message: string;
-  resource_limit?: ResourceLimitInfo;
-  /**
-   * On the `check_output_bytes` diagnostic only: how many written methods
-   * it stands for, the last ones in name order. They are not reported, and
-   * fail closed.
-   */
-  unreported_methods?: number;
-}
-
-/** A completed compatibility check. */
-export interface CompatibilityReport {
-  ok: true;
-  /** True when no diagnostic is an error. Warnings do not clear it. */
-  compatible: boolean;
-  written: Identities;
-  /**
-   * The live interface's identities. Compare `interface_id` with the one
-   * recorded when the written file was made to tell an unchanged interface
-   * from one that changed compatibly.
-   */
-  live: Identities;
-  /** By written method name, each method's errors before its warnings. */
-  diagnostics: CompatibilityDiagnostic[];
-}
-
-/**
- * A check that could not run. `input` names the side that failed when one
- * side does not compile or declares no service; a malformed request has none.
- */
-export interface CheckFailure extends Failure {
-  input?: "written" | "live";
-}
-
-/**
- * Check that a live interface is still compatible with a written one: the
- * live service must be a Candid subtype of the written one. Every written
- * method must exist in the live service with the same mode, its arguments
- * contravariant and its results covariant; methods only the live service
- * has are ignored. A hand-written subset `.did` is as valid a written side
- * as a projection.
- *
- * @example
- * const report = await checkCompatible(writtenDid, liveDid);
- * if (report.ok && !report.compatible) {
- *   for (const item of report.diagnostics) console.error(item.method, item.code, item.path);
- * }
- */
-export function checkCompatible(
-  written: Sources,
-  live: Sources,
-): Promise<CompatibilityReport | CheckFailure>;
-
-/**
- * What happened to one entry of `meant gen`.
- *
- * - `written`: the entry generated and at least one of its two files was
- *   created or changed on disk.
- * - `unchanged`: the entry generated and both files already held exactly
- *   those bytes; nothing was written.
- * - `drifted`: `--check` only — at least one file is missing or differs from
- *   what the entry now generates; nothing was written.
- * - `failed`: the entry did not generate; `diagnostics` says why. A compile
- *   failure writes nothing for the entry.
- */
-export type CliEntryStatus = "written" | "unchanged" | "drifted" | "failed";
-
-/**
- * The identities of one compiled `gen` entry, equal to its envelope's
- * `contract.identities` under the key names {@link Identities} uses.
- */
-export interface CliIdentities {
-  /** The Contract identity: the whole canonical graph, declarations included. */
-  contract_id: string;
-  /**
-   * The interface identity: only what the service reaches. Absent when the
-   * `.did` has no actor, as in the envelope.
-   */
-  interface_id?: string;
-}
-
-/** One entry's part of the `--json` document. */
-export interface CliEntryReport {
-  /** The entry exactly as it was given on the command line. */
-  entry: string;
-  status: CliEntryStatus;
-  /** The generated module's path: `-o` joined with `<stem>.ts`. */
-  module: string;
-  /** The contract envelope's path: `-o` joined with `<stem>.envelope.json`. */
-  envelope: string;
-  /**
-   * The entry's identities, the same the human report prints. Present on
-   * every entry that compiled (`written`, `unchanged`, `drifted`), with or
-   * without `--check`; absent on a `failed` entry.
-   */
-  identities?: CliIdentities;
-  /**
-   * What the module leaves out, exactly as `didToModule` returns it. Empty
-   * for a `failed` entry and when nothing is omitted. Omissions never make an
-   * entry fail.
-   */
-  omitted: Omission[];
-  /**
-   * The compiler's diagnostics for a `failed` entry, in the same shape the
-   * library returns; empty otherwise. Failures that occur before compilation
-   * use the same shape with codes this CLI originates:
-   * `did_file_read_error`, `did_source_not_found`, `resource_limit_exceeded`,
-   * `nondeterministic_output` and `internal_error` (which carries no `phase`).
-   */
-  diagnostics: Diagnostic[];
-}
-
-/**
- * The one document `meant gen … --json` prints on stdout, and
- * nothing else: stderr stays empty. The process exit code is 0 exactly when
- * `ok` is true, and 1 otherwise. A usage error exits 64 and prints no
- * document.
- */
-export interface CliReport {
-  /**
-   * The document's version. It changes only when an existing field's meaning
-   * or shape changes; adding a field does not change it. Refuse a version
-   * you do not know.
-   */
-  schemaVersion: 1;
-  /** True when no entry is `failed` or `drifted`. Omissions do not clear it. */
-  ok: boolean;
-  /** Whether `--check` was given. */
-  check: boolean;
-  /** One report per entry, in command-line order. */
-  entries: CliEntryReport[];
-  /**
-   * Every path `--check` found missing or different from what its entry now
-   * generates, in entry order, module before envelope. Always empty without
-   * `--check`, and for a `failed` entry.
-   */
-  drift: string[];
-}

package/lib/index.js

@@ -1,131 +0,0 @@
-// The library surface of @meantjs/cli: data in, data out.
-// Every function hands one JSON-serializable request to the wasm compiler and
-// return its parsed JSON response verbatim — no eval and no network, nothing
-// thrown for data errors, and no filesystem access from the wasm side (this
-// module reads the embedded artifact itself on Node):
-// a failure is the same `{ ok: false, diagnostics }` document the native
-// `meant` CLI prints, passed through byte-for-byte.
-
-import initWasm, {
-  checkCompatible as wasmCheckCompatible,
-  didToContract as wasmDidToContract,
-  didToDocAttributes as wasmDidToDocAttributes,
-  didToModule as wasmDidToModule,
-  projectDid as wasmProjectDid,
-} from "../wasm/candid_core_wasm.js";
-
-let initialized;
-
-/**
- * Initialize the embedded wasm module once. Node needs no argument (the
- * artifact is read from this package); a browser may also pass nothing (the
- * artifact is fetched relative to this module) or supply its own
- * `BufferSource`/`URL`/`Response`.
- */
-export function init(input) {
-  if (initialized === undefined) {
-    initialized = (async () => {
-      if (input === undefined && typeof process !== "undefined" && process.versions?.node) {
-        const { readFile } = await import("node:fs/promises");
-        const bytes = await readFile(
-          new URL("../wasm/candid_core_wasm_bg.wasm", import.meta.url),
-        );
-        await initWasm({ module_or_path: bytes });
-      } else {
-        await initWasm(input === undefined ? undefined : { module_or_path: input });
-      }
-    })();
-  }
-  return initialized;
-}
-
-function sourcesOf(sources) {
-  return typeof sources === "string" ? { source: sources } : sources;
-}
-
-function requestOf(sources) {
-  return JSON.stringify(sourcesOf(sources));
-}
-
-/**
- * Compile Candid sources into a one-document ContractEnvelope carrying the
- * `org.candid-core.field-names/v1` extension — exactly the document
- * `meant compile <path> --envelope` emits, ready for
- * `schemaFromContract`. `sources` is Candid text, or
- * `{ entry, files: { name: text } }` for a multi-file bundle.
- *
- * Returns the parsed envelope (`"contract" in result`), or
- * `{ ok: false, diagnostics }` with the compiler's diagnostics verbatim.
- */
-export async function didToContract(sources) {
-  await init();
-  return JSON.parse(wasmDidToContract(requestOf(sources)));
-}
-
-/**
- * Generate the `@meantjs/schema` TypeScript module for Candid sources.
- * Returns `{ ok: true, module, omitted }` with the generated text —
- * byte-identical to what the Rust-native generator emits — and the
- * declarations and methods it left out, or `{ ok: false, diagnostics }`.
- */
-export async function didToModule(sources) {
-  await init();
-  return JSON.parse(wasmDidToModule(requestOf(sources)));
-}
-
-/**
- * Compile Candid sources and read the `@name(key = value, …)` attributes in
- * their doc comments (`docs/doc-attributes.md` in the Meant
- * repository). Returns `{ ok: true, contract, source_info, doc_attributes }`
- * — the Contract and SourceInfo `meant compile <path>` prints, plus
- * every documented item's prose and attributes keyed by its SourceInfo path
- * — or `{ ok: false, diagnostics }`: `doc_attribute_malformed`,
- * `doc_attribute_duplicate_key`, `resource_limit_exceeded`, or the
- * compiler's diagnostics.
- */
-export async function didToDocAttributes(sources) {
-  await init();
-  return JSON.parse(wasmDidToDocAttributes(requestOf(sources)));
-}
-
-/**
- * Project Candid sources onto the methods named: a self-contained `.did`
- * holding exactly those methods of the service and every declaration they
- * reach, deterministic to the byte for the same sources and the same set of
- * names, whatever their order.
- *
- * Returns `{ ok: true, did, methods, input, projection }` — the text, the
- * methods it holds in name order, and the identities of the input and of
- * the projection — or `{ ok: false, diagnostics }`: `unknown_method` (one
- * per distinct name the service lacks; the failure's first diagnostic lists
- * the service's methods in its `notes`, once), `empty_method_list`,
- * `no_service`, `resource_limit_exceeded` (`projection_bytes`: the
- * projection would pass the compiler's 1 MiB bound on one source;
- * `projection_diagnostic_bytes`: the unknown-method diagnostics would pass
- * 4 MiB as the failure writes them, and the names left are counted, not
- * reported), or the compiler's diagnostics.
- */
-export async function projectDid(sources, methods) {
-  await init();
-  return JSON.parse(wasmProjectDid(JSON.stringify({ ...sourcesOf(sources), methods })));
-}
-
-/**
- * Check that a live interface is still compatible with a written one: every
- * method of the written service exists in the live one with the same mode,
- * and the live method's type is a Candid subtype of the written one.
- * Methods only the live service has are ignored.
- *
- * Returns `{ ok: true, compatible, written, live, diagnostics }`, where each
- * diagnostic names its method and, inside a type, the path where the check
- * failed; or `{ ok: false, input, diagnostics }` when a side does not
- * compile (`input` names it). The diagnostics are bounded at 4 MiB as the
- * response writes them: past that bound one last diagnostic, which names no
- * method, counts the methods left in `unreported_methods`.
- */
-export async function checkCompatible(written, live) {
-  await init();
-  return JSON.parse(
-    wasmCheckCompatible(JSON.stringify({ written: sourcesOf(written), live: sourcesOf(live) })),
-  );
-}