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

6.8 KiB Raw
/**
 * Resolving re-exports.
 *
 * A facade module — `zena:map`, `zena:collections` — declares nothing
 * of its own and re-exports from files that are private to its
 * package. Recording the specifier is not enough for a reader: the
 * declarations are not documented anywhere else, so `zena:map` would
 * document as an empty page.
 *
 * So each re-export is followed to the file it names, that file is
 * walked, and the declarations it carries are copied into the facade
 * under the names the facade exports them as. Each copy records where
 * it is declared, so a consumer can say "re-exported from …" and link
 * there when that module is documented too.
 */

import { CompilationResult, CompilerTarget, ProgramCheckResult } from 'compiler/compiler';
import { extractModule, ExtractOptions } from './extract.zena';
import { Naming } from './ids.zena';
import { ModelLinker } from './links.zena';
import {
  DocDeclaration, DocModule, DocReexport, DocReexportName,
} from './model.zena';

/**
 * How many re-export hops to follow.
 *
 * A facade re-exporting a facade is normal; a chain longer than this is
 * a cycle, and following it forever would hang rather than report.
 */
let MAX_DEPTH = 8;

/**
 * Every file walked into the model so far in this run, by canonical
 * path.
 *
 * A module's own walk goes in as soon as it is documented, so a facade
 * re-exporting `zena:array` copies from the page that already exists
 * rather than walking `array.zena` again; and a private file several
 * facades re-export — three re-export `collections/hash-map.zena` — is
 * walked for the first of them and read from here by the rest.
 *
 * Walking is pure: the model is derived from source text, so a cached
 * walk stays correct across the compiler replacements batching does.
 */
export final class WalkCache {
  #modules = new Map<String, DocModule>();

  has(canonical: String): boolean {
    return this.#modules.has(canonical);
  }

  get(canonical: String): DocModule {
    return this.#modules[canonical];
  }

  put(canonical: String, module: DocModule): void {
    this.#modules[canonical] = module;
  }
}

/**
 * Copies re-exported declarations into `module`.
 *
 * `result` and `checked` come from compiling that module, so every file
 * it re-exports from is already loaded and checked.
 */
export function resolveReexports(
  module: DocModule,
  packageName: String,
  packageRoot: String,
  target: CompilerTarget,
  result: CompilationResult,
  checked: ProgramCheckResult,
  options: ExtractOptions,
  cache: WalkCache
): void {
  if (module.reexports.length == 0) {
    return;
  }
  // Relative specifiers resolve against the file, not the module's
  // public id: `./encoding.zena` inside `zena:url/index.zena` is a
  // sibling of that file, and resolving it from `zena:url` would look
  // beside `url.zena` at the stdlib root instead.
  let names = new Naming(packageName, packageRoot);
  for (let reexport in module.reexports) {
    copyFrom(module, reexport, result.entry.path, names, target, result,
        checked, options, cache, 0);
  }
}

/** Follows one re-export and copies what it carries. */
function copyFrom(
  into: DocModule,
  reexport: DocReexport,
  referrer: String,
  names: Naming,
  target: CompilerTarget,
  result: CompilationResult,
  checked: ProgramCheckResult,
  options: ExtractOptions,
  cache: WalkCache,
  depth: i32
): void {
  if (depth > MAX_DEPTH) {
    return;
  }
  let source = sourceModule(reexport.from, referrer, names, target, result,
      checked, options, cache);
  if (source == null) {
    return;
  }
  reexport.resolved = source.id;

  if (reexport.isAll) {
    for (let declaration in source.declarations) {
      adopt(into, declaration, declaration.name, source.id);
    }
  } else {
    for (let entry in reexport.names) {
      let declaration = find(source, entry.source);
      if (declaration != null) {
        adopt(into, declaration, entry.exported, source.id);
      }
    }
  }

  // The source may itself be a facade. Follow its re-exports for the
  // names this one asked for, and for everything under `export *`.
  for (let nested in source.reexports) {
    let wanted = if (reexport.isAll) {
      nested
    } else {
      narrow(nested, reexport, source)
    };
    if (wanted != null) {
      copyFrom(into, wanted, source.file, names, target, result, checked,
          options, cache, depth + 1);
    }
  }
}

/**
 * The names of `nested` that `outer` still needs, or null if none.
 *
 * `export {HashMap} from 'zena:collections'` where `zena:collections`
 * itself re-exports `HashMap` and much else: only `HashMap` crosses.
 */
function narrow(
  nested: DocReexport,
  outer: DocReexport,
  source: DocModule
): DocReexport | null {
  let wanted = new Array<DocReexportName>(2);
  for (let name in outer.names) {
    if (source.declares(name.source)) {
      continue;
    }
    if (nested.isAll) {
      wanted.push(new DocReexportName(name.exported, name.source));
    } else {
      for (let carried in nested.names) {
        if (carried.exported == name.source) {
          wanted.push(new DocReexportName(name.exported, carried.source));
        }
      }
    }
  }
  if (wanted.length == 0) {
    return null;
  }
  return new DocReexport(nested.from, wanted, false);
}

/** The module a specifier names, walked and cached. */
function sourceModule(
  specifier: String,
  referrer: String,
  names: Naming,
  target: CompilerTarget,
  result: CompilationResult,
  checked: ProgramCheckResult,
  options: ExtractOptions,
  cache: WalkCache
): DocModule | null {
  let resolved = target.resolve(specifier, referrer);
  let canonical = resolved.path;
  if (cache.has(canonical)) {
    return cache.get(canonical);
  }
  for (let file in result.files) {
    if (file.path == canonical) {
      let entry = checked.results[canonical];
      let model = if (entry == null) { null } else { entry.model };
      let id = names.idOf(canonical);
      // `file` holds the canonical path, so a nested re-export resolves
      // its relative specifiers against the right directory.
      let walked = extractModule(id, id, canonical, file.ast, model, options,
          new ModelLinker(model, names));
      cache.put(canonical, walked);
      return walked;
    }
  }
  return null;
}

function find(module: DocModule, name: String): DocDeclaration | null {
  for (let declaration in module.declarations) {
    if (declaration.name == name) {
      return declaration;
    }
  }
  return null;
}

/**
 * Copies a declaration into a module under the name it exports it as.
 *
 * A name the module already documents wins, so a module that both
 * declares `Map` and re-exports another one documents its own.
 */
function adopt(
  into: DocModule,
  declaration: DocDeclaration,
  name: String,
  from: String
): void {
  if (into.declares(name)) {
    return;
  }
  let copy = declaration.renamed(name, `${into.id}#${name}`,
      into.anchors.take(name));
  copy.reexportedFrom = from;
  into.declarations.push(copy);
}
  • 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