zenadoc 0.0.2-preview.1

Extracts a Zena package's public API as JSON

Readme Files Dependencies Versions

zenadoc#

Extracts a Zena package's public API from source and serializes it as JSON: every module the package exports, the declarations in each, their members, signatures, resolved type links, and doc comments.

Usage#

Command Line#

zena doc ./my-package -o api.json   # a package with zena-package.json
zena doc ./src                      # any directory, to stdout
zena doc main.zena                  # a single file

Library API#

import { documentPackage, DocumentOptions } from 'zenadoc';
import { loadPackage } from 'zenadoc/package';
import { packageToJson } from 'zenadoc/json';

let pkg = await loadPackage('./my-package');
let result = await documentPackage(pkg, new DocumentOptions());
let json = packageToJson(result.docs);

Libraries#

  • zenadoc / zenadoc/document — compiles and documents a package (documentPackage, DocumentOptions, DocumentResult)
  • zenadoc/package — discovers a package's exported modules from zena-package.json or the filesystem (loadPackage, Package, ModuleSpec)
  • zenadoc/model — API documentation model (DocPackage, DocModule, DocDeclaration, DocMember, TypeRef, TypeLink, DeclarationKind, MemberKind)
  • zenadoc/json — serializes a DocPackage to JSON (packageToJson)
  • zenadoc/extract — walks a parsed Module AST into a DocModule (extractModule, ExtractOptions)
  • zenadoc/reexports — follows re-exported declarations across modules (resolveReexports, WalkCache)
  • zenadoc/inherit — copies inherited members from supertypes (inheritMembers)
  • zenadoc/links — resolves type references to declaration targets via scope analysis (linkModule, ScopeIndex)
  • zenadoc/publish — rewrites declaration links to their public hosting module (publishLinks)
  • zenadoc/type-text — renders type annotations to text and records declaration spans (renderTypeAnnotation)
  • zenadoc/ids — formats module and declaration anchor IDs (moduleId, anchorFor)

License#

MIT

7.6 KiB Raw
/**
 * Serializing the API model.
 *
 * Field order is the order written here and `JsonObject` preserves it,
 * so the same source produces the same bytes: the output can be checked
 * in, diffed in review, and used as a snapshot test.
 *
 * Empty collections and null fields are omitted. A consumer reads a
 * missing `members` the same way it reads an empty one, and leaving
 * them out keeps a package's JSON readable by a person.
 */

import { JsonObject, JsonArray, JsonValue, stringify } from 'zena:json';
import { DocComment, DocTag } from 'compiler/doc-comment';
import {
  DocDeclaration, DocLoc, DocMember, DocModule, DocPackage, DocParam,
  DocReexport, DocTypeParam, TypeRef, DeclarationKind, declarationKindName,
  memberKindName,
} from './model.zena';

/** The format version, so a consumer can refuse what it cannot read. */
export let ZENADOC_FORMAT_VERSION = 1;


/** The whole package as pretty-printed JSON. */
export function packageToJson(pkg: DocPackage): String {
  return stringify(packageObject(pkg), '  ');
}

export function packageObject(pkg: DocPackage): JsonObject {
  let out = new JsonObject();
  out['zenadoc'] = new Box<f64>(ZENADOC_FORMAT_VERSION as f64);
  let meta = new JsonObject();
  meta['name'] = pkg.name;
  meta['root'] = pkg.root;
  let version = pkg.version;
  if (version != null) {
    meta['version'] = version;
  }
  out['package'] = meta;
  let modules = new JsonArray();
  for (let module in pkg.modules) {
    modules.push(moduleObject(module));
  }
  out['modules'] = modules;
  return out;
}

function moduleObject(module: DocModule): JsonObject {
  let out = new JsonObject();
  out['id'] = module.id;
  out['name'] = module.name;
  out['file'] = module.file;
  putDoc(out, module.doc);
  if (module.reexports.length > 0) {
    let reexports = new JsonArray();
    for (let reexport in module.reexports) {
      reexports.push(reexportObject(reexport));
    }
    out['reexports'] = reexports;
  }
  let declarations = new JsonArray();
  for (let declaration in module.declarations) {
    declarations.push(declarationObject(declaration));
  }
  out['declarations'] = declarations;
  return out;
}

function reexportObject(reexport: DocReexport): JsonObject {
  let out = new JsonObject();
  out['from'] = reexport.from;
  let resolved = reexport.resolved;
  if (resolved != null) {
    out['resolved'] = resolved;
  }
  if (reexport.isAll) {
    out['all'] = new Box<boolean>(true);
  } else {
    let names = new JsonArray();
    for (let name in reexport.names) {
      names.push(name.exported);
    }
    out['names'] = names;
  }
  return out;
}

function declarationObject(declaration: DocDeclaration): JsonObject {
  let out = new JsonObject();
  out['kind'] = declarationKindName(declaration.kind);
  out['name'] = declaration.name;
  out['id'] = declaration.id;
  out['anchor'] = declaration.anchor;
  out['signature'] = declaration.signature;
  if (!declaration.exported) {
    out['exported'] = new Box<boolean>(false);
  }
  let reexportedFrom = declaration.reexportedFrom;
  if (reexportedFrom != null) {
    out['reexportedFrom'] = reexportedFrom;
  }
  if (declaration.modifiers.length > 0) {
    out['modifiers'] = stringArray(declaration.modifiers);
  }
  putTypeParams(out, declaration.typeParameters);
  putParams(out, declaration.parameters);
  putType(out, 'type', declaration.type);
  putType(out, 'extends', declaration.superClass);
  // An interface's supertypes are written `extends`, a class's
  // `implements`; the model holds one list, and the key says which
  // keyword the source used.
  let supertypeKey = if (declaration.kind == DeclarationKind.Interface) {
    'extends'
  } else {
    'implements'
  };
  putTypes(out, supertypeKey, declaration.interfaces);
  putTypes(out, 'mixins', declaration.mixins);
  putDoc(out, declaration.doc);
  putLoc(out, declaration.loc);
  if (declaration.members.length > 0) {
    let members = new JsonArray();
    for (let member in declaration.members) {
      members.push(memberObject(member));
    }
    out['members'] = members;
  }
  return out;
}

function memberObject(member: DocMember): JsonObject {
  let out = new JsonObject();
  out['kind'] = memberKindName(member.kind);
  out['name'] = member.name;
  out['id'] = member.id;
  out['anchor'] = member.anchor;
  out['signature'] = member.signature;
  if (member.isStatic) {
    out['static'] = new Box<boolean>(true);
  }
  if (member.isAbstract) {
    out['abstract'] = new Box<boolean>(true);
  }
  let inheritedFrom = member.inheritedFrom;
  if (inheritedFrom != null) {
    out['inheritedFrom'] = inheritedFrom;
  }
  let mutability = member.mutability;
  if (mutability != null) {
    out['mutability'] = mutability;
  }
  putTypeParams(out, member.typeParameters);
  putParams(out, member.parameters);
  putType(out, 'type', member.type);
  putDoc(out, member.doc);
  putLoc(out, member.loc);
  return out;
}

function putTypeParams(out: JsonObject, params: Array<DocTypeParam>): void {
  if (params.length == 0) {
    return;
  }
  let array = new JsonArray();
  for (let param in params) {
    let entry = new JsonObject();
    entry['name'] = param.name;
    putType(entry, 'bound', param.bound);
    putType(entry, 'default', param.defaultType);
    array.push(entry);
  }
  out['typeParameters'] = array;
}

function putParams(out: JsonObject, params: Array<DocParam>): void {
  if (params.length == 0) {
    return;
  }
  let array = new JsonArray();
  for (let param in params) {
    let entry = new JsonObject();
    entry['name'] = param.name;
    putType(entry, 'type', param.type);
    if (param.optional) {
      entry['optional'] = new Box<boolean>(true);
    }
    let fallback = param.defaultValue;
    if (fallback != null) {
      entry['default'] = fallback;
    }
    array.push(entry);
  }
  out['parameters'] = array;
}

function typeObject(type: TypeRef) {
  let entry = new JsonObject();
  entry['text'] = type.text;
  if (type.links.length > 0) {
    let links = new JsonArray();
    for (let link in type.links) {
      let one = new JsonObject();
      one['start'] = new Box<f64>(link.start as f64);
      one['end'] = new Box<f64>(link.end as f64);
      one['id'] = link.id;
      links.push(one);
    }
    entry['links'] = links;
  }
  return entry;
}

function putType(out: JsonObject, key: String, type: TypeRef | null): void {
  if (type == null) {
    return;
  }
  out[key] = typeObject(type);
}

function putTypes(out: JsonObject, key: String, types: Array<TypeRef>): void {
  if (types.length == 0) {
    return;
  }
  let array = new JsonArray();
  for (let type in types) {
    array.push(typeObject(type));
  }
  out[key] = array;
}

function putDoc(out: JsonObject, doc: DocComment | null): void {
  if (doc == null) {
    return;
  }
  let entry = new JsonObject();
  if (doc.summary.length > 0) {
    entry['summary'] = doc.summary;
  }
  if (doc.description.length > 0) {
    entry['description'] = doc.description;
  }
  if (doc.tags.length > 0) {
    let tags = new JsonArray();
    for (let tag in doc.tags) {
      let tagObject = new JsonObject();
      tagObject['tag'] = tag.name;
      if (tag.subject.length > 0) {
        tagObject['name'] = tag.subject;
      }
      if (tag.text.length > 0) {
        tagObject['text'] = tag.text;
      }
      tags.push(tagObject);
    }
    entry['tags'] = tags;
  }
  out['doc'] = entry;
}

function putLoc(out: JsonObject, loc: DocLoc | null): void {
  if (loc == null) {
    return;
  }
  let entry = new JsonObject();
  entry['file'] = loc.file;
  entry['line'] = new Box<f64>(loc.line as f64);
  entry['column'] = new Box<f64>(loc.column as f64);
  out['loc'] = entry;
}

function stringArray(values: Array<String>): JsonArray {
  let array = new JsonArray();
  for (let value in values) {
    array.push(value);
  }
  return array;
}
  • compiler compiler.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19
  • compiler compiler.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1