How the ego-lite `help()` Function Uses JSDoc Parsing for Runtime Documentation

The help() function in citrolabs/ego-lite queries a pre-computed documentation map generated at build time from JSDoc comments, enabling instant runtime access without file-system operations or parsing overhead.

In the citrolabs/ego-lite repository, the help() utility provides interactive documentation for helper functions by leveraging a sophisticated build-time pipeline that extracts JSDoc metadata and embeds it directly into the runtime bundle. This approach eliminates the need for the browser or runtime environment to parse source code files, instead relying on a baked-in JSON documentation map that is loaded on demand. Understanding how the help() function is implemented using JSDoc parsing at runtime requires examining the three-stage pipeline: extraction, embedding, and lookup.

Build-Time JSDoc Extraction Pipeline

The documentation generation begins long before the code reaches the browser. The scripts/extract-help-docs.mjs script analyzes the bundled JavaScript using the Acorn parser to create an AST, then walks the tree to find block comments preceding function declarations.

Parsing the Source with Acorn

Inside extract-help-docs.mjs, the parse() function from Acorn processes the bundled JavaScript to produce an AST. The extractor collects all block comments and correlates each comment with the immediately following function declaration. This correlation ensures that documentation attaches to the correct helper regardless of minification or bundling artifacts.

Structuring Helper Documentation

Once a comment block is identified, the parseJSDoc() function transforms the raw JSDoc into a structured object containing description, params, and returns fields. The extractParams() helper enriches this data by walking the AST to resolve default values, identify rest parameters (...args), and flag optional parameters. Each helper yields a HelperDoc object containing:

• The helper name and signature
• Parameter list with types and descriptions
• Return type annotation
• Async flag status

The extractHelpDocs() function returns an array of these objects, ready for serialization.

Embedding Documentation into the Runtime

During the bundling phase, scripts/build.mjs executes the extraction and embeds the results into the runtime. The embedHelpDocs routine JSON-stringifies the HelperDoc array and injects it into src/help-runtime.ts, replacing the placeholder string __EGO_EMBEDDED_HELP_DOCS__. This compile-time injection means the runtime code carries its own documentation payload, requiring no external file access to serve help content.

Runtime Lookup and Caching

At runtime, src/help-runtime.ts implements the public help() API. Rather than parsing comments, it operates on the embedded JSON data through an efficient caching mechanism.

The getDocsMap() Cache

The getDocsMap() function lazily deserializes the injected JSON using parseEmbeddedDocs() and stores the result in a Map<string, HelperDoc>. This cache persists for the lifetime of the module, ensuring repeated calls to help() return instantly without re-parsing the JSON payload.

Three Query Modes

The help() function supports three distinct calling conventions:

• No arguments – Returns documentation for all available helpers present in the current helpers object.
• Single string – Returns the HelperDoc for the specified helper name, or an "Unknown helper" string if not found.
• Multiple strings – Returns an array of HelperDoc objects, inserting a placeholder object for any unrecognized names.

Formatting Helper Documentation

For human-readable output, the formatHelp() function (located in src/format.ts) consumes a HelperDoc object and generates a formatted string. The output includes the description, @param lines with types and defaults, the @returns annotation, and a reconstructed function signature showing parameter optionality.

// Query examples assuming the ego-lite helper context
console.log(help());                         // Array of all helper docs
console.log(help('click'));                  // Doc for the 'click' helper
console.log(help('click', 'type', 'foo'));   // Docs for click, type, and placeholder for foo

// Pretty-print a single helper
const doc = help('click');
console.log(formatHelp(doc));

Typical output includes the description, parameter details, and signature:

Clicks an element located by a CSS selector.
@param selector string — The CSS selector of the element.
@param button? string — Mouse button to press (default: "left").
@returns void

click(selector, button?) → void

Summary

• Build-time extraction: scripts/extract-help-docs.mjs uses Acorn to parse JSDoc comments from the bundled source and creates structured HelperDoc objects.
• Compile-time embedding: scripts/build.mjs injects the JSON-serialized documentation into src/help-runtime.ts via the __EGO_EMBEDDED_HELP_DOCS__ placeholder.
• Runtime caching: getDocsMap() lazily parses the embedded JSON once and caches it in a Map for O(1) lookups.
• Multiple access patterns: help() supports querying all helpers, single helpers by name, or multiple helpers in one call.
• Formatting utility: formatHelp() renders HelperDoc objects into human-readable strings with signatures and parameter descriptions.

Frequently Asked Questions

Does help() parse JSDoc comments at runtime?

No. The help() function reads from a pre-computed JSON map that was generated at build time. The actual JSDoc parsing occurs in scripts/extract-help-docs.mjs using the Acorn parser, long before the code executes in the browser or runtime environment.

What tool extracts the JSDoc metadata for embedding?

The extraction is performed by the Node.js script scripts/extract-help-docs.mjs. This script uses Acorn to generate an AST from the bundled JavaScript, then walks the tree to match block comments with function declarations and resolve parameter details via extractParams().

How does the runtime access the embedded documentation?

The bundled JavaScript contains a placeholder string __EGO_EMBEDDED_HELP_DOCS__ that gets replaced with the stringified JSON documentation array during the build process. At runtime, getDocsMap() in src/help-runtime.ts parses this JSON once and caches the results in a Map keyed by helper name.

What information is stored in a HelperDoc object?

Each HelperDoc contains the helper name, function signature, JSDoc description, an array of parameter objects (with names, types, defaults, and optionality flags), the return type, and a boolean indicating whether the function is async.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}