function readDocSurface
readDocSurface(doc: DenoDocJson): PackageSurface

Reads a package's discoverable surface out of parsed deno doc --json output.

This is the whole of the JSON-shape knowledge, kept pure so it can be tested against captured fixtures without a subprocess. A symbol counts as a coder factory when it is declared as a function whose return type renders as Coder — a string match, per ADR 0002, so a coder hidden behind a type alias that renders as something else is invisible here.

Coders that take no required arguments are listed first, because those are the ones the CLI can invoke on the user's behalf (ADR 0005). Declaration order is preserved within each group.

The single node is read without choosing between nodes, which is sound only because the specifier named one module: a directory, whose output holds one node per file under it, never reaches here (./target.ts, ADR 0004).

Zero nodes is a successful discovery of nothing, not an impossibility. deno doc exits 0 with an empty nodes map for a directory holding no module files, and this destructured Object.entries(doc.nodes)[0] unguarded, so the answer to "what does this expose?" was an uncaught TypeError with a stack trace through the CLI's own frames. An empty surface is what the caller already knows how to answer — the "exposes no coders" screen — so that is what it returns.

Examples

Read the coders of a package

import { assertEquals } from "@std/assert";
import { readDocSurface } from "./discover.ts";

const surface = readDocSurface({
  nodes: {
    "jsr:@binstruct/arp": {
      module_doc: { doc: "ARP packet encoding and decoding.\nRFC 826." },
      symbols: [{
        name: "arpData",
        declarations: [{
          kind: "function",
          location: { filename: "https://jsr.io/@binstruct/arp/0.3.0/mod.ts" },
          jsDoc: { doc: "Creates a coder for ARP packets.\n" },
          def: {
            params: [],
            returnType: {
              repr: "Coder",
              value: { typeParams: [{ repr: "ArpData" }] },
            },
          },
        }],
      }],
    },
  },
});

assertEquals(surface.version, "0.3.0");
assertEquals(surface.summary, "ARP packet encoding and decoding.");
assertEquals(surface.coders, [{
  name: "arpData",
  decodedType: "ArpData",
  summary: "Creates a coder for ARP packets.",
  requiredParams: 0,
}]);

A document with no nodes exposes no coders

import { assertEquals } from "@std/assert";
import { readDocSurface } from "./discover.ts";

assertEquals(readDocSurface({ nodes: {} }), { coders: [] });

Parameters

Parsed output of deno doc --json --quiet <specifier>

Return Type

The module summary, resolved version and coder list

Usage

import { readDocSurface } from "mod.ts";