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
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
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|
|