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.8 KiB Raw
/**
 * Finding a package's modules.
 *
 * A package is a directory. If it holds a manifest, the manifest's
 * export map is the module list; otherwise every `.zena` file under the
 * root is a module. A single `.zena` file is a package of one module.
 *
 * Two manifest filenames are read, because the standard library's is
 * spelled differently: `zena-package.json` with an `exports` map, and
 * `stdlib-manifest.json` with a `modules` map. Both mean the same
 * thing. See docs/design/zenadoc.md and docs/design/package-manifest.md.
 */

import { parseJson, JsonValue, JsonObject } from 'zena:json';
import { Future } from 'zena:async';
import { exists, isDirectory, listDir, readFile, FileType } from 'zena:fs';
import { basename, dirname, join2 } from 'zena:path';
import { growable } from 'zena:core';

let PACKAGE_MANIFEST = 'zena-package.json';
let STDLIB_MANIFEST = 'stdlib-manifest.json';

/** One module a package exposes. */
export final class PackageModule(
  /** The module's name within the package, e.g. `array` or `bench`. */
  name: String,

  /** The entry file, relative to the package root. */
  file: String
)

/** A package as zenadoc sees it: a name, a root, and a module list. */
export final class Package {
  name: String;
  root: String;
  var version: String | null = null;
  var modules = new Array<PackageModule>(0);

  new(this.name, this.root);
}

/**
 * The package at `path`.
 *
 * `path` is a directory or a single `.zena` file. `name` overrides the
 * name the manifest or the directory would give.
 */
export async function loadPackage(
  path: String,
  name: String | null = null,
  target: String = 'zena-component'
): Future<Package> {
  if (!(await exists(path))) {
    throw new Error('no such path: ' + path);
  }
  if (!(await isDirectory(path))) {
    return singleFilePackage(path, name);
  }
  let manifestPath = await manifestIn(path);
  if (manifestPath == null) {
    return await openPackage(path, name);
  }
  return await manifestPackage(path, manifestPath, name, target);
}

/** The manifest in a directory, whichever of the two names it uses. */
async function manifestIn(root: String): Future<String | null> {
  let preferred = join2(root, PACKAGE_MANIFEST);
  if (await exists(preferred)) {
    return preferred;
  }
  let stdlib = join2(root, STDLIB_MANIFEST);
  if (await exists(stdlib)) {
    return stdlib;
  }
  return null;
}

async function manifestPackage(
  root: String,
  manifestPath: String,
  override: String | null,
  target: String
): Future<Package> {
  let json = parseJson(await readFile(manifestPath));
  let manifest = json as JsonObject;
  var exports = manifest['exports'];
  if (exports == null) {
    exports = manifest['modules'];
  }
  let name = override ?? manifestName(manifest, root);
  // The manifest may sit above the sources it describes: a package's
  // libraries are in its `source` directory, `src` by default
  // (package-manifest.md, "source"), and the stdlib's manifest,
  // `packages/stdlib/stdlib-manifest.json`, names `zena` as its `root`.
  // Every entry file is relative to that directory, not to the manifest.
  let declaredRoot = if (manifestPath.endsWith(PACKAGE_MANIFEST)) manifest['source'] ?? 'src' else manifest['root'];
  let sourceRoot = if (declaredRoot is String && declaredRoot != '.') {
    join2(root, declaredRoot)
  } else {
    root
  };
  let out = new Package(name, sourceRoot);
  let version = manifest['version'];
  if (version is String) {
    out.version = version;
  }
  if (exports == null) {
    // A manifest with no export map says nothing about which modules
    // are public, so every file is.
    out.modules = await openModules(sourceRoot);
    return out;
  }
  let modules = new Array<PackageModule>(16);
  (exports as JsonObject).forEach((moduleName, value) => {
    let file = entryFileOf(moduleName, value, target);
    if (file != null) {
      modules.push(new PackageModule(moduleName, file));
    }
  });
  out.modules = sortModules(modules);
  return out;
}

/**
 * A module's entry file on a target.
 *
 * `{}` means `<name>.zena` and `path` names the file. A `virtual`
 * module has one entry file per target and exists only on the targets
 * it names — `zena:wasi` is not a module a `zena`
 * program can import, and documenting it as one would describe an API
 * that is not there.
 *
 * An `internal` module is not one either. It carries a manifest entry
 * because that is what selects its file per target, and the package's
 * own modules are the only ones allowed to import it.
 */
function entryFileOf(
  name: String,
  value: JsonValue,
  target: String
): String | null {
  if (!(value is JsonObject)) {
    return name + '.zena';
  }
  let entry = value;
  let internal = entry['internal'];
  if (internal is Box<boolean> && internal.value) {
    return null;
  }
  let path = entry['path'];
  if (path is String) {
    return path;
  }
  let virtual = entry['virtual'];
  if (virtual is JsonObject) {
    let file = virtual[target];
    if (file is String) {
      return file;
    }
    return null;
  }
  return name + '.zena';
}

function manifestName(manifest: JsonObject, root: String): String {
  let name = manifest['name'];
  if (name is String) {
    return name;
  }
  return basename(root);
}

/** Every `.zena` file under a root, as a module named by its path. */
async function openPackage(root: String, override: String | null): Future<Package> {
  let name = override ?? basename(root);
  let out = new Package(name, root);
  out.modules = await openModules(root);
  return out;
}

async function openModules(root: String): Future<GrowableArray<PackageModule>> {
  let modules = new Array<PackageModule>(16);
  await collectZenaFiles(root, '', modules);
  return sortModules(modules);
}

async function collectZenaFiles(
  root: String,
  prefix: String,
  out: GrowableArray<PackageModule>
): Future<void> {
  let dir = if (prefix.length == 0) { root } else { join2(root, prefix) };
  for (let entry in await listDir(dir)) {
    if (entry.name == '.' || entry.name == '..') {
      continue;
    }
    let relative = if (prefix.length == 0) {
      entry.name
    } else {
      join2(prefix, entry.name)
    };
    if (entry.fileType == FileType.Directory) {
      await collectZenaFiles(root, relative, out);
    } else if (entry.fileType == FileType.RegularFile &&
        entry.name.endsWith('.zena')) {
      out.push(new PackageModule(
          relative.sliceBytes(0, relative.length - 5), relative));
    }
  }
}

function singleFilePackage(path: String, override: String | null): Package {
  let file = basename(path);
  let name = override ?? stripExtension(file);
  let out = new Package(name, dirname(path));
  let modules = growable<PackageModule>([
    new PackageModule(stripExtension(file), file),
  ]);
  out.modules = modules;
  return out;
}

/**
 * Modules in name order.
 *
 * A manifest's JSON object preserves the order it was written in, and a
 * directory listing is in whatever order the host returns. Sorting
 * makes the output depend on the package's contents and nothing else.
 */
function sortModules(
  modules: GrowableArray<PackageModule>
): GrowableArray<PackageModule> {
  // Insertion sort: a package has tens of modules, not thousands.
  var i = 1;
  while (i < modules.length) {
    let current = modules[i];
    var j = i - 1;
    while (j >= 0 && precedes(current.name, modules[j].name)) {
      modules[j + 1] = modules[j];
      j -= 1;
    }
    modules[j + 1] = current;
    i += 1;
  }
  return modules;
}

/** Whether `a` sorts before `b`, byte by byte. */
function precedes(a: String, b: String): boolean {
  let shorter = if (a.length < b.length) { a.length } else { b.length };
  var i = 0;
  while (i < shorter) {
    let x = a.getByteAt(i);
    let y = b.getByteAt(i);
    if (x != y) {
      return x < y;
    }
    i += 1;
  }
  return a.length < b.length;
}


function stripExtension(file: String): String {
  if (file.endsWith('.zena')) {
    return file.sliceBytes(0, file.length - 5);
  }
  return file;
}
  • 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