@travetto/doc 8.0.0-alpha.2 → 8.0.0-alpha.21

package/src/render/markdown.ts

@@ -1,22 +1,23 @@
 import fs from 'node:fs/promises';
 
-import { Runtime, RuntimeIndex } from '@travetto/runtime';
+import { HELP_FLAG } from '@travetto/cli';
 import { PackageUtil } from '@travetto/manifest';
+import { CodecUtil, Runtime, RuntimeError, RuntimeIndex } from '@travetto/runtime';
 
-import type { RenderProvider } from '../types.ts';
 import { c, getComponentName } from '../jsx.ts';
-import { MODULES } from '../mapping/module.ts';
 import { LIBRARIES } from '../mapping/library.ts';
-import type { RenderContext } from './context.ts';
-import { DocResolveUtil } from '../util/resolve.ts';
+import { MODULES } from '../mapping/module.ts';
+import type { RenderProvider } from '../types.ts';
 import { PackageDocUtil } from '../util/package.ts';
+import { DocResolveUtil } from '../util/resolve.ts';
+import type { RenderContext } from './context.ts';
 
 export const Markdown: RenderProvider<RenderContext> = {
   ext: 'md',
   finalize: (text, context) => {
     const brand = `<!-- ${context.generatedStamp} -->\n<!-- ${context.rebuildStamp} -->`;
     const cleaned = text
-      .replace(/(\[[^\]]+\]\([^)]+\))([A-Za-z0-9$]+)/g, (_, link, value) => value === 's' ? _ : `${link} ${value}`)
+      .replace(/(\[[^\]]+\]\([^)]+\))([A-Za-z0-9$]+)/g, (_, link, value) => (value === 's' ? _ : `${link} ${value}`))
       .replace(/(\S)\n(#)/g, (_, left, right) => `${left}\n\n${right}`);
     return `${brand}\n${cleaned}`;
   },
@@ -29,7 +30,7 @@ export const Markdown: RenderProvider<RenderContext> = {
   li: async ({ recurse, stack }) => {
     const parent = stack.toReversed().find(node => node.type === 'ol' || node.type === 'ul');
     const depth = stack.filter(node => node.type === 'ol' || node.type === 'ul').length;
-    return `${'   '.repeat(depth)}${(parent && parent.type === 'ol') ? '1.' : '* '} ${await recurse()}\n`;
+    return `${'   '.repeat(depth)}${parent && parent.type === 'ol' ? '1.' : '* '} ${await recurse()}\n`;
   },
   table: async ({ recurse }) => `${await recurse()}`,
   tbody: async ({ recurse }) => `${await recurse()}`,
@@ -44,8 +45,8 @@ export const Markdown: RenderProvider<RenderContext> = {
   h4: async ({ recurse }) => `\n#### ${await recurse()}\n\n`,
   Execution: async ({ context, node, props, createState }) => {
     const output = await context.execute(node);
-    const displayCmd = props.config?.formatCommand?.(props.cmd, props.args ?? []) ??
-      `${node.props.cmd} ${(node.props.args ?? []).join(' ')}`;
+    const displayCmd =
+      props.config?.formatCommand?.(props.cmd, props.args ?? []) ?? `${node.props.cmd} ${(node.props.args ?? []).join(' ')}`;
     const state = createState('Terminal', {
       language: 'bash',
       title: node.props.title,
@@ -53,6 +54,31 @@ export const Markdown: RenderProvider<RenderContext> = {
     });
     return Markdown.Terminal(state);
   },
+  CliHelpExecution: async ({ context, props, createState }) => {
+    const { name: command } = context.resolveCliCommandFromClass(props.commandClass);
+    return await Markdown.Execution(
+      createState('Execution', {
+        title: `Help for ${command}`,
+        cmd: 'trv',
+        args: [command, HELP_FLAG],
+        config: { ...props.config }
+      })
+    );
+  },
+  CliHelpDescription: async ({ context, props }) => {
+    const { description = '' } = context.resolveCliCommandFromClass(props.commandClass);
+    let text = description;
+    if (props.short) {
+      text = CodecUtil.readFirstLine(text);
+    }
+    return text;
+  },
+  CliHelpSection: async ({ context, props, recurse }) => {
+    const { name: command } = context.resolveCliCommandFromClass(props.commandClass);
+    const title = `CLI - ${command}`;
+    const body = await recurse();
+    return `\n## ${title}\n${body}`;
+  },
   Install: async ({ context, node }) =>
     `\n\n**Install: ${node.props.title}**
 \`\`\`bash
@@ -101,8 +127,8 @@ ${context.cleanText(content.text)}
   },
 
   Image: async ({ props, context }) => {
-    if (!/^https?:/.test(props.href) && !(await fs.stat(props.href).catch(() => false))) {
-      throw new Error(`${props.href} is not a valid location`);
+    if (!/^https?:/.test(props.href) && !(await fs.stat(props.href, { throwIfNoEntry: false }))) {
+      throw new RuntimeError(`${props.href} is not a valid location`);
     }
     return `![${props.title}](${context.link(props.href)})`;
   },

package/src/render/renderer.ts

@@ -1,30 +1,28 @@
 import path from 'node:path';
 
 import { type ManifestContext, PackageUtil } from '@travetto/manifest';
-import { castTo, type Class, Runtime } from '@travetto/runtime';
+import { type Class, castTo, Runtime, RuntimeError } from '@travetto/runtime';
 
-import { EMPTY_ELEMENT, getComponentName, type JSXElementByFn, type c } from '../jsx.ts';
+import { isJSXElement, type JSXElement, JSXFragmentType } from '../../support/jsx-runtime.ts';
+import { type c, EMPTY_ELEMENT, getComponentName, type JSXElementByFn } from '../jsx.ts';
 import type { DocumentShape, RenderProvider, RenderState } from '../types.ts';
 import { DocFileUtil } from '../util/file.ts';
-
 import { RenderContext } from './context.ts';
 import { Html } from './html.ts';
 import { Markdown } from './markdown.ts';
 
-import { isJSXElement, type JSXElement, JSXFragmentType } from '../../support/jsx-runtime.ts';
-
 const providers = { [Html.ext]: Html, [Markdown.ext]: Markdown };
 
 /**
  * Doc Renderer
  */
 export class DocRenderer {
-
   static async get(file: string, manifest: Pick<ManifestContext, 'workspace'>): Promise<DocRenderer> {
     const document = await Runtime.importFrom<DocumentShape>(file);
     const pkg = PackageUtil.readPackage(manifest.workspace.path);
     const repoBaseUrl = pkg.travetto?.doc?.baseUrl ?? manifest.workspace.path;
-    return new DocRenderer(document,
+    return new DocRenderer(
+      document,
       new RenderContext(file, repoBaseUrl, path.resolve(pkg.travetto?.doc?.root ?? manifest.workspace.path))
     );
   }
@@ -38,11 +36,7 @@ export class DocRenderer {
     this.#support = support;
   }
 
-  async #buildLink(
-    renderer: RenderProvider<RenderContext>,
-    cls: Class,
-    title?: string
-  ) {
+  async #buildLink(renderer: RenderProvider<RenderContext>, cls: Class, title?: string) {
     const source = DocFileUtil.readSource(cls);
     if (source) {
       title = DocFileUtil.isDecorator(cls.name, source.file) ? `@${title ?? cls.name}` : (title ?? cls.name);
@@ -53,7 +47,11 @@ export class DocRenderer {
       });
       // @ts-expect-error
       const state: RenderState<JSXElementByFn<'CodeLink'>, RenderContext> = {
-        node, props: node.props, recurse: async () => '', context: this.#support, stack: []
+        node,
+        props: node.props,
+        recurse: async () => '',
+        context: this.#support,
+        stack: []
       };
       // @ts-expect-error
       state.createState = (key, props) => this.createState(state, key, props);
@@ -66,7 +64,6 @@ export class DocRenderer {
     input: JSXElement[] | JSXElement | string | bigint | object | number | boolean | null | undefined,
     stack: JSXElement[] = []
   ): Promise<string | undefined> {
-
     if (input === null || input === undefined) {
       return '';
     } else if (Array.isArray(input)) {
@@ -99,21 +96,27 @@ export class DocRenderer {
         const recurse = () => this.#render(renderer, final.props.children ?? [], [...stack, final]);
         // @ts-expect-error
         const state: RenderState<JSXElement, RenderContext> = {
-          node: final, props: final.props, recurse, stack, context: this.#support
+          node: final,
+          props: final.props,
+          recurse,
+          stack,
+          context: this.#support
         };
         state.createState = (key, props) => this.createState(state, key, props);
         // @ts-expect-error
         return renderer[name](state);
       } else {
         console.log(final);
-        throw new Error(`Unknown element: ${final.type}`);
+        throw new RuntimeError(`Unknown element: ${final.type}`);
       }
     } else {
       switch (typeof input) {
-        case 'string': return input.replace(/&nbsp;/g, ' ');
+        case 'string':
+          return input.replace(/&nbsp;/g, ' ');
         case 'number':
         case 'bigint':
-        case 'boolean': return `${input}`;
+        case 'boolean':
+          return `${input}`;
         case 'object': {
           if (input) {
             return await this.#buildLink(renderer, castTo(input.constructor), input.constructor.name.replace(/^[$]/, ''));
@@ -124,7 +127,7 @@ export class DocRenderer {
           return await this.#buildLink(renderer, castTo(input));
         }
       }
-      throw new Error(`Unknown object type: ${typeof input}`);
+      throw new RuntimeError(`Unknown object type: ${typeof input}`);
     }
   }
 
@@ -144,18 +147,17 @@ export class DocRenderer {
    */
   async render(format: keyof typeof providers): Promise<string> {
     if (!providers[format]) {
-      throw new Error(`Unknown renderer with format: ${format}`);
+      throw new RuntimeError(`Unknown renderer with format: ${format}`);
     }
     if (!this.#rootNode) {
-      this.#rootNode = (Array.isArray(this.#root.text) || isJSXElement(this.#root.text)) ?
-        this.#root.text : await (this.#root.text());
+      this.#rootNode = Array.isArray(this.#root.text) || isJSXElement(this.#root.text) ? this.#root.text : await this.#root.text();
     }
 
     const text = await this.#render(providers[format], this.#rootNode);
-    let cleaned = `${text?.replace(/\n{3,100}/msg, '\n\n').trim()}\n`;
+    let cleaned = `${text?.replace(/\n{3,100}/gms, '\n\n').trim()}\n`;
     if (this.#root.wrap?.[format]) {
       cleaned = this.#root.wrap[format](cleaned);
     }
     return providers[format].finalize(cleaned, this.#support);
   }
-}
+}

package/src/types.ts

@@ -1,5 +1,5 @@
-import type { JSXElementByFn, c } from './jsx.ts';
 import type { JSXElement, ValidHtmlTags } from '../support/jsx-runtime.ts';
+import type { c, JSXElementByFn } from './jsx.ts';
 
 export type Wrapper = Record<string, (cnt: string) => string>;
 
@@ -25,11 +25,10 @@ export type RenderState<T extends JSXElement, C> = {
 /**
  * Renderer
  */
-export type RenderProvider<C> =
-  {
-    ext: string;
-    finalize: (text: string, ctx: C) => string;
-  } &
-  { [K in ValidHtmlTags]: (state: RenderState<JSXElement<K>, C>) => Promise<string>; } &
+export type RenderProvider<C> = {
+  ext: string;
+  finalize: (text: string, ctx: C) => string;
+} & { [K in ValidHtmlTags]: (state: RenderState<JSXElement<K>, C>) => Promise<string> } & {
   // @ts-expect-error
-  { [K in keyof typeof c]: (state: RenderState<JSXElementByFn<K>, C>) => Promise<string>; };
+  [K in keyof typeof c]: (state: RenderState<JSXElementByFn<K>, C>) => Promise<string>;
+};

package/src/util/file.ts

@@ -1,8 +1,8 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
-import { RuntimeError, Runtime, RuntimeIndex } from '@travetto/runtime';
 import { type ManifestModuleFileType, ManifestModuleUtil } from '@travetto/manifest';
+import { Runtime, RuntimeError, RuntimeIndex } from '@travetto/runtime';
 
 import type { CodeSourceInput } from './types.ts';
 
@@ -23,21 +23,20 @@ const MOD_FILE_TO_LANG: Record<ManifestModuleFileType, string | undefined> = {
 const EXT_TO_LANG: Record<string, string> = {
   '.yaml': 'yaml',
   '.yml': 'yaml',
-  '.sh': 'bash',
+  '.sh': 'bash'
 };
 
-type SourceOutput = { content: string, language: string, file: string };
-type SnippetOutput = { file: string, startIdx: number, lines: string[], language: string };
+type SourceOutput = { content: string; language: string; file: string };
+type SnippetOutput = { file: string; startIdx: number; lines: string[]; language: string };
 
 /**
  * Standard file utilities
  */
 export class DocFileUtil {
-
   static #decCache: Record<string, boolean> = {};
 
   static isFile(file: string): boolean {
-    return /^[@:A-Za-z0-9\/\\\-_.]+[.]([a-z]{2,10})$/.test(file);
+    return /^[@:A-Za-z0-9/\\_.-]+[.]([a-z]{2,10})$/.test(file);
   }
 
   static readSource(input: Exclude<CodeSourceInput, Promise<string>>): SourceOutput {
@@ -66,16 +65,14 @@ export class DocFileUtil {
     }
 
     if (content) {
-      content = content.split(/\n/)
-        .map(line => line
-          .replace(ESLINT_PATTERN, '')
-          .replace(ENV_KEY, (_, key) => `'${key}'`)
-        )
+      content = content
+        .split(/\n/)
+        .map(line => line.replace(ESLINT_PATTERN, '').replace(ENV_KEY, (_, key) => `'${key}'`))
         .join('\n')
-        .replace(/^\/\/# sourceMap.*$/gsm, '')
-        .replace(/[ ]*[/][/][ ]*@ts-expect-error[^\n]*\n/gsm, '') // Excluding errors
-        .replace(/^[ ]*[/][/][ ]*[{][{][^\n]*\n/gsm, '') // Excluding conditional comments, full-line
-        .replace(/[ ]*[/][/][ ]*[{][{][^\n]*/gsm, ''); // Excluding conditional comments
+        .replace(/^\/\/# sourceMap.*$/gms, '')
+        .replace(/[ ]*[/][/][ ]*@ts-expect-error[^\n]*\n/gms, '') // Excluding errors
+        .replace(/^[ ]*[/][/][ ]*[{][{][^\n]*\n/gms, '') // Excluding conditional comments, full-line
+        .replace(/[ ]*[/][/][ ]*[{][{][^\n]*/gms, ''); // Excluding conditional comments
     }
 
     if (file !== undefined) {
@@ -102,7 +99,6 @@ export class DocFileUtil {
    * Determine if a file is a decorator
    */
   static isDecorator(name: string, file: string): boolean {
-
     const key = `${name}:${file}`;
     if (key in this.#decCache) {
       return this.#decCache[key];
@@ -131,32 +127,36 @@ export class DocFileUtil {
    */
   static buildOutline(code: string): string {
     let methodPrefix = '';
-    code = code.split(/\n/).map((line) => {
-      if (!methodPrefix) {
-        const info = line.match(/^(\s{0,50})(?:(private|public)\s{1,10})?(?:static\s{1,10})?(?:async\s{1,10})?(?:[*]\s{0,10})?(?:(?:get|set)\s{1,10})?(\S{1,200})[<(](.{0,500})/);
-        if (info) {
-          const [, space, __name, rest] = info;
-          if (!rest.endsWith(';')) {
-            if (/\s{0,50}[{]\s{0,50}return.{0,200}$/.test(line)) {
-              return line.replace(/\s{0,50}[{]\s{0,50}return.{0,200}$/, ';');
-            } else {
-              methodPrefix = space;
-              return line.replace(/\s{0,50}[{]\s{0,50}$/, ';');
+    code = code
+      .split(/\n/)
+      .map(line => {
+        if (!methodPrefix) {
+          const info = line.match(
+            /^(\s{0,50})(?:(private|public)\s{1,10})?(?:static\s{1,10})?(?:async\s{1,10})?(?:[*]\s{0,10})?(?:(?:get|set)\s{1,10})?(\S{1,200})[<(](.{0,500})/
+          );
+          if (info) {
+            const [, space, __name, rest] = info;
+            if (!rest.endsWith(';')) {
+              if (/\s{0,50}[{]\s{0,50}return.{0,200}$/.test(line)) {
+                return line.replace(/\s{0,50}[{]\s{0,50}return.{0,200}$/, ';');
+              } else {
+                methodPrefix = space;
+                return line.replace(/\s{0,50}[{]\s{0,50}$/, ';');
+              }
             }
           }
+          return line;
+        } else {
+          if (line.startsWith(`${methodPrefix}}`)) {
+            methodPrefix = '';
+          }
+          return '';
         }
-        return line;
-      } else {
-        if (line.startsWith(`${methodPrefix}}`)) {
-          methodPrefix = '';
-        }
-        return '';
-      }
-    })
+      })
       .filter(line => !/#|(\b(private|protected)\b)/.test(line))
       .filter(line => !!line)
       .join('\n');
 
     return code;
   }
-}
+}

package/src/util/package.ts

@@ -1,4 +1,4 @@
-import { PACKAGE_MANAGERS, type NodePackageManager } from '@travetto/manifest';
+import { type NodePackageManager, PACKAGE_MANAGERS } from '@travetto/manifest';
 import { Runtime } from '@travetto/runtime';
 
 export class PackageDocUtil {
@@ -8,8 +8,10 @@ export class PackageDocUtil {
   static getPackageCommand(pkg: string, args: string[] = [], manager?: NodePackageManager): string {
     switch (manager ?? Runtime.workspace.manager) {
       case 'npm':
-      case 'yarn': return `npx ${pkg} ${args.join(' ')}`.trim();
-      case 'pnpm': return `pnpm ${pkg} ${args.join(' ')}`.trim();
+      case 'yarn':
+        return `npx ${pkg} ${args.join(' ')}`.trim();
+      case 'pnpm':
+        return `pnpm ${pkg} ${args.join(' ')}`.trim();
     }
   }
 
@@ -18,9 +20,12 @@ export class PackageDocUtil {
    */
   static getWorkspaceInitCommand(manager?: NodePackageManager): string {
     switch (manager ?? Runtime.workspace.manager) {
-      case 'npm': return 'npm init -f';
-      case 'yarn': return 'yarn init -y';
-      case 'pnpm': return 'pnpm init -y';
+      case 'npm':
+        return 'npm init -f';
+      case 'yarn':
+        return 'yarn init -y';
+      case 'pnpm':
+        return 'pnpm init -y';
     }
   }
 
@@ -29,9 +34,12 @@ export class PackageDocUtil {
    */
   static getInstallCommand(pkg: string, production = false, manager?: NodePackageManager): string {
     switch (manager ?? Runtime.workspace.manager) {
-      case 'npm': return `npm install ${production ? '' : '--save-dev '}${pkg}`;
-      case 'yarn': return `yarn add ${production ? '' : '--dev '}${pkg}`;
-      case 'pnpm': return `pnpm add ${production ? '' : '--dev '}${pkg}`;
+      case 'npm':
+        return `npm install ${production ? '' : '--save-dev '}${pkg}`;
+      case 'yarn':
+        return `yarn add ${production ? '' : '--dev '}${pkg}`;
+      case 'pnpm':
+        return `pnpm add ${production ? '' : '--dev '}${pkg}`;
     }
   }
 
@@ -39,8 +47,6 @@ export class PackageDocUtil {
    * Get install example for a given package
    */
   static getInstallInstructions(pkg: string, production = false): string {
-    return PACKAGE_MANAGERS
-      .map(manager => this.getInstallCommand(pkg, production, manager.type))
-      .join('\n\n# or\n\n');
+    return PACKAGE_MANAGERS.map(manager => this.getInstallCommand(pkg, production, manager.type)).join('\n\n# or\n\n');
   }
-}
+}

package/src/util/resolve.ts

@@ -1,24 +1,23 @@
 import { DocFileUtil } from './file.ts';
 import type { CodeProps, CodeSourceInput } from './types.ts';
 
-export type ResolvedRef = { title: string, file: string, line: number };
-export type ResolvedCode = { text: string, language: string, file?: string };
-export type ResolvedSnippet = { text: string, language: string, file: string, line: number };
-export type ResolvedSnippetLink = { file: string, line: number };
+export type ResolvedRef = { title: string; file: string; line: number };
+export type ResolvedCode = { text: string; language: string; file?: string };
+export type ResolvedSnippet = { text: string; language: string; file: string; line: number };
+export type ResolvedSnippetLink = { file: string; line: number };
 
 /**
  * Resolve utilities
  */
 export class DocResolveUtil {
-
   static async resolveRef(title: string, file: string): Promise<ResolvedRef> {
-
     let line = 0;
     const result = DocFileUtil.readSource(file);
     file = result.file;
 
     if (result.content) {
-      line = result.content.split(/\n/g)
+      line = result.content
+        .split(/\n/g)
         .findIndex(lineText => new RegExp(`(class|interface|function)[ ]+${RegExp.escape(title)}`).test(lineText));
       if (line < 0) {
         line = 0;
@@ -67,9 +66,9 @@ export class DocResolveUtil {
 
   static applyCodePropDefaults(props: CodeProps): void {
     const type = typeof props.src === 'function' ? props.src : undefined;
-    props.startRe ??= (type ? new RegExp(`^(export)?\\s*(interface|class)\\s+${RegExp.escape(type.name)}\\b`) : undefined);
-    props.language ??= (type ? 'typescript' : undefined);
-    props.endRe ??= (type ? /^[}]/ : undefined);
-    props.title ??= typeof props.src == 'function' ? props.src.name.replace(/^[$]/, '') : undefined;
+    props.startRe ??= type ? new RegExp(`^(export)?\\s*(interface|class)\\s+${RegExp.escape(type.name)}\\b`) : undefined;
+    props.language ??= type ? 'typescript' : undefined;
+    props.endRe ??= type ? /^[}]/ : undefined;
+    props.title ??= typeof props.src === 'function' ? props.src.name.replace(/^[$]/, '') : undefined;
   }
-}
+}

package/src/util/run.ts

@@ -1,9 +1,10 @@
-import os from 'node:os';
-import util from 'node:util';
 import { spawn } from 'node:child_process';
+import os from 'node:os';
 import path from 'node:path';
+import util from 'node:util';
 
 import { Env, ExecUtil, Runtime, RuntimeIndex } from '@travetto/runtime';
+
 import type { RunConfig } from './types.ts';
 
 export const COMMON_DATE = new Date('2029-03-14T00:00:00.000-0400').getTime();
@@ -25,7 +26,8 @@ class DocState {
 
   getId(id: string): string {
     if (!this.ids[id]) {
-      this.ids[id] = ' '.repeat(id.length)
+      this.ids[id] = ' '
+        .repeat(id.length)
         .split('')
         .map(_ => Math.trunc(this.rng() * 16).toString(16))
         .join('');
@@ -42,7 +44,7 @@ export class DocRunUtil {
 
   /** Build working directory from config */
   static workingDirectory(config: RunConfig): string {
-    return path.resolve(config.module ? RuntimeIndex.getModule(config.module)?.sourcePath! : Runtime.mainSourcePath);
+    return path.resolve(config.module ? (RuntimeIndex.getModule(config.module)?.sourcePath ?? undefined!) : Runtime.mainSourcePath);
   }
 
   /**
@@ -50,20 +52,22 @@ export class DocRunUtil {
    */
   static cleanRunOutput(text: string, config: RunConfig): string {
     const rootPath = this.workingDirectory(config);
-    text = util.stripVTControlCharacters(text.trim())
+    text = util
+      .stripVTControlCharacters(text.trim())
       .replaceAll(rootPath, '.')
       .replaceAll(os.tmpdir(), '/tmp')
       .replaceAll(Runtime.workspace.path, '<workspace-root>')
-      .replace(/[/]tmp[/][a-z_A-Z0-9\/\-]+/g, '/tmp/<temp-folder>')
+      .replace(/[/]tmp[/][a-z_A-Z0-9/-]+/g, '/tmp/<temp-folder>')
       .replace(/^(\s*framework:\s*')(\d+[.]\d+)[^']*('[,]?\s*)$/gm, (_, pre, ver, post) => `${pre}${ver}.x${post}`)
       .replace(/^(\s*nodeVersion:\s*'v)(\d+)[^']*('[,]?\s*)$/gm, (_, pre, ver, post) => `${pre}${ver}.x.x${post}`)
       .replace(/^(.{1,4})?Compiling[.]*/, '') // Compiling message, remove
-      .replace(/[A-Za-z0-9_.\-\/\\]+\/travetto\/module\//g, '@travetto/')
+      .replace(/[A-Za-z0-9_./\\-]+\/travetto\/module\//g, '@travetto/')
       .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}([.]\d{3})?Z?/g, this.#docState.getDate.bind(this.#docState))
-      .replace(/\b[0-9a-f]{4}[0-9a-f\-]{8,40}\b/ig, this.#docState.getId.bind(this.#docState))
+      .replace(/\b[0-9a-f]{4}[0-9a-f-]{8,40}\b/gi, this.#docState.getId.bind(this.#docState))
       .replace(/(\d+[.]\d+[.]\d+)-(alpha|rc)[.]\d+/g, (all, value) => value);
     if (config.filter || config.rewrite) {
-      text = text.split(/\n/g)
+      text = text
+        .split(/\n/g)
         .filter(line => config.filter?.(line) ?? true)
         .map(line => config.rewrite?.(line) ?? line)
         .join('\n');
@@ -108,4 +112,4 @@ export class DocRunUtil {
 
     return this.cleanRunOutput(final, config);
   }
-}
+}

package/src/util/types.ts

@@ -11,4 +11,4 @@ export type RunConfig = {
 
 export type CodeSourceInput = string | Promise<string> | Function;
 
-export type CodeProps = { title?: string, src: CodeSourceInput, language?: string, outline?: boolean, startRe?: RegExp, endRe?: RegExp };
+export type CodeProps = { title?: string; src: CodeSourceInput; language?: string; outline?: boolean; startRe?: RegExp; endRe?: RegExp };

package/support/cli.doc.ts

@@ -1,23 +1,25 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { ExecUtil, Env, Runtime, WatchUtil } from '@travetto/runtime';
-import { type CliCommandShape, CliCommand } from '@travetto/cli';
-import { MinLength, Validator } from '@travetto/schema';
+import { CliCommand, type CliCommandShape } from '@travetto/cli';
 import { PackageUtil } from '@travetto/manifest';
+import { Env, ExecUtil, Runtime, WatchUtil } from '@travetto/runtime';
+import { MinLength, Validator } from '@travetto/schema';
 
 /**
- * Command line support for generating module docs.
+ * Generate documentation outputs from a module `DOC.tsx` entry file.
+ *
+ * Supports multiple output formats/targets and optional watch mode for
+ * iterative documentation authoring.
  */
 @CliCommand()
-@Validator(async (cmd) => {
+@Validator(async cmd => {
   const docFile = path.resolve(cmd.input);
-  if (!(await fs.stat(docFile).catch(() => false))) {
+  if (!(await fs.stat(docFile, { throwIfNoEntry: false }))) {
     return { message: `input: ${cmd.input} does not exist`, path: 'input', source: 'flag', kind: 'invalid' };
   }
 })
 export class DocCommand implements CliCommandShape {
-
   /** Input File */
   input = 'DOC.tsx';
 
@@ -33,7 +35,7 @@ export class DocCommand implements CliCommandShape {
     Env.TRV_ROLE.set('doc');
     Env.TRV_CLI_IPC.clear();
     Env.TRV_LOG_PLAIN.set(true);
-    Env.FORCE_COLOR.set(false);// Prevent restarting
+    Env.FORCE_COLOR.set(false); // Prevent restarting
   }
 
   async runWatch(): Promise<void> {
@@ -54,8 +56,7 @@ export class DocCommand implements CliCommandShape {
     const { DocRenderer } = await import('../src/render/renderer.ts');
     const ctx = await DocRenderer.get(this.input, Runtime);
     const outputs = this.outputs.map(output =>
-      output.includes('.') ? [path.extname(output).replace('.', ''), path.resolve(output)] :
-        [output, null] as const
+      output.includes('.') ? [path.extname(output).replace('.', ''), path.resolve(output)] : ([output, null] as const)
     );
 
     for (const [format, out] of outputs) {
@@ -75,4 +76,4 @@ export class DocCommand implements CliCommandShape {
 
     return this.watch ? this.runWatch() : this.render();
   }
-}
+}