zenadoc 0.0.2-preview.1
Extracts a Zena package's public API as JSON
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 fromzena-package.jsonor the filesystem (loadPackage,Package,ModuleSpec)zenadoc/model— API documentation model (DocPackage,DocModule,DocDeclaration,DocMember,TypeRef,TypeLink,DeclarationKind,MemberKind)zenadoc/json— serializes aDocPackageto JSON (packageToJson)zenadoc/extract— walks a parsedModuleAST into aDocModule(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
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|
|