@travetto/doc 3.4.3 → 4.0.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/doc",
-  "version": "3.4.3",
+  "version": "4.0.0-rc.1",
   "description": "Documentation support for the Travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,13 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/base": "^3.4.2",
+    "@travetto/base": "^4.0.0-rc.1",
+    "@travetto/terminal": "^4.0.0-rc.1",
     "@types/prismjs": "^1.26.3",
     "prismjs": "^1.29.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^3.4.7"
+    "@travetto/cli": "^4.0.0-rc.1"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/mapping/lib-mapping.ts

@@ -39,6 +39,7 @@ export const LIB_MAPPING = {
   UUID: { title: 'UUID', href: 'https://en.wikipedia.org/wiki/Universally_unique_identifier' },
 
   // Node
+  Process: { title: 'process', href: 'https://nodejs.org/api/process.html' },
   ChildProcess: { title: 'child_process', href: 'https://nodejs.org/api/child_process.html' },
   AsyncHooks: { title: 'async_hooks', href: 'https://nodejs.org/api/async_hooks.html' },
   Http: { title: 'http', href: 'https://nodejs.org/api/http.html' },
@@ -97,7 +98,7 @@ export const LIB_MAPPING = {
   // Rest
   Express: { title: 'express', href: 'https://expressjs.com' },
   Passport: { title: 'passport', href: 'http://passportjs.org' },
-  Busboy: { title: 'busboy', href: 'https://github.com/mscdex/busboy' },
+  Busboy: { title: '@fastify/busboy', href: 'https://github.com/fastify/busboy' },
   Cookies: { title: 'cookies', href: 'https://www.npmjs.com/package/cookies' },
   ServerlessExpress: { title: 'aws-serverless-express', href: 'https://github.com/awslabs/aws-serverless-express/blob/master/README.md' },
   AwsLambdaFastify: { title: '@fastify/aws-lambda', href: 'https://github.com/fastify/aws-lambda-fastify/blob/master/README.md' },

package/src/render/context.ts

@@ -1,6 +1,6 @@
 import { createElement, JSXRuntimeTag } from '@travetto/doc/jsx-runtime';
 
-import { PackageUtil, path, RootIndex } from '@travetto/manifest';
+import { PackageUtil, path, RuntimeIndex } from '@travetto/manifest';
 
 import { JSXElementByFn, c } from '../jsx';
 import { DocResolveUtil, ResolvedCode, ResolvedRef, ResolvedSnippetLink } from '../util/resolve';
@@ -35,12 +35,12 @@ export class RenderContext {
 
   constructor(file: string, baseUrl: string, repoRoot: string) {
 
-    const manifestPkg = PackageUtil.readPackage(RootIndex.getModule('@travetto/manifest')!.sourcePath);
+    const manifestPkg = PackageUtil.readPackage(RuntimeIndex.getModule('@travetto/manifest')!.sourcePath);
 
     this.file = path.toPosix(file);
     this.baseUrl = baseUrl;
     this.repoRoot = repoRoot;
-    this.travettoBaseUrl = repoRoot.includes('travetto.github') ? repoRoot : manifestPkg.travetto!.docBaseUrl!;
+    this.travettoBaseUrl = repoRoot.includes('travetto.github') ? repoRoot : manifestPkg.travetto!.doc!.baseUrl!;
   }
 
   /**
@@ -105,7 +105,7 @@ export class RenderContext {
    * Resolve code link
    */
   async resolveCodeLink(node: JSXElementByFn<'CodeLink'>): Promise<ResolvedSnippetLink> {
-    const src = typeof node.props.src === 'string' ? node.props.src : RootIndex.getFunctionMetadata(node.props.src)!.source;
+    const src = typeof node.props.src === 'string' ? node.props.src : RuntimeIndex.getFunctionMetadata(node.props.src)!.source;
     return DocResolveUtil.resolveCodeLink(src, node.props.startRe);
   }
 
@@ -113,7 +113,7 @@ export class RenderContext {
    * Resolve code/config
    */
   async resolveCode(node: JSXElementByFn<'Code' | 'Config'>): Promise<ResolvedCode> {
-    const src = typeof node.props.src === 'string' ? node.props.src : RootIndex.getFunctionMetadata(node.props.src)!.source;
+    const src = typeof node.props.src === 'string' ? node.props.src : RuntimeIndex.getFunctionMetadata(node.props.src)!.source;
     return node.props.startRe ?
       DocResolveUtil.resolveSnippet(src, node.props.startRe, node.props.endRe, node.props.outline) :
       DocResolveUtil.resolveCode(src, node.props.language, node.props.outline);

package/src/render/html.ts

@@ -1,7 +1,7 @@
-import fs from 'fs/promises';
+import fs from 'node:fs/promises';
 
 import { JSXElement } from '@travetto/doc/jsx-runtime';
-import { RootIndex, PackageUtil } from '@travetto/manifest';
+import { RuntimeIndex, PackageUtil, RuntimeContext } from '@travetto/manifest';
 
 import { highlight } from './code-highlight';
 import { RenderProvider, RenderState } from '../types';
@@ -144,8 +144,8 @@ yarn add ${el.props.pkg}
   Header: async ({ props }) => `<h1>${props.title} ${props.description ? `\n<small>${props.description}</small>\n` : ''}</h1>\n`,
 
   StdHeader: async state => {
-    const mod = state.el.props.mod ?? RootIndex.mainModuleName;
-    const pkg = PackageUtil.readPackage(RootIndex.getModule(mod)!.sourcePath);
+    const mod = state.el.props.mod ?? RuntimeContext.main.name;
+    const pkg = PackageUtil.readPackage(RuntimeIndex.getModule(mod)!.sourcePath);
     const title = pkg.travetto?.displayName ?? pkg.name;
     const desc = pkg.description;
     let install = '';

package/src/render/markdown.ts

@@ -1,5 +1,5 @@
-import fs from 'fs/promises';
-import { PackageUtil, RootIndex } from '@travetto/manifest';
+import fs from 'node:fs/promises';
+import { PackageUtil, RuntimeIndex, RuntimeContext } from '@travetto/manifest';
 
 import { RenderProvider } from '../types';
 import { c, getComponentName } from '../jsx';
@@ -108,8 +108,8 @@ ${context.cleanText(content.text)}
   Header: async ({ props }) => `# ${props.title}\n${props.description ? `## ${props.description}\n` : ''}\n`,
 
   StdHeader: async state => {
-    const mod = state.el.props.mod ?? RootIndex.mainModuleName;
-    const pkg = PackageUtil.readPackage(RootIndex.getModule(mod)!.sourcePath);
+    const mod = state.el.props.mod ?? RuntimeContext.main.name;
+    const pkg = PackageUtil.readPackage(RuntimeIndex.getModule(mod)!.sourcePath);
     const title = pkg.travetto?.displayName ?? pkg.name;
     const desc = pkg.description;
     let install = '';

package/src/render/renderer.ts

@@ -1,6 +1,6 @@
-import { ManifestRoot, PackageUtil, path, RootIndex } from '@travetto/manifest';
+import { ManifestContext, PackageUtil, path, RuntimeIndex } from '@travetto/manifest';
 
-import { isJSXElement, JSXElement, createFragment, JSXFragmentType } from '@travetto/doc/jsx-runtime';
+import { isJSXElement, JSXElement, JSXFragmentType } from '@travetto/doc/jsx-runtime';
 
 import { EMPTY_ELEMENT, getComponentName, JSXElementByFn, c } from '../jsx';
 import { DocumentShape, RenderProvider, RenderState } from '../types';
@@ -17,16 +17,17 @@ const providers = { [Html.ext]: Html, [Markdown.ext]: Markdown };
  */
 export class DocRenderer {
 
-  static async get(file: string, manifest: ManifestRoot): Promise<DocRenderer> {
-    const mod = RootIndex.getFromSource(file)?.import;
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const res = await import(mod!) as DocumentShape;
+  static async get(file: string, manifest: ManifestContext): Promise<DocRenderer> {
+    const mod = RuntimeIndex.getFromSource(file)?.import;
+    if (!mod) {
+      throw new Error(`Unable to render ${file}, not in the manifest`);
+    }
+    const res: DocumentShape = await import(mod);
 
-    const pkg = PackageUtil.readPackage(manifest.workspacePath);
-    const mainPath = path.resolve(manifest.workspacePath, manifest.mainFolder);
-    const repoBaseUrl = pkg.travetto?.docBaseUrl ?? mainPath;
+    const pkg = PackageUtil.readPackage(manifest.workspace.path);
+    const repoBaseUrl = pkg.travetto?.doc?.baseUrl ?? manifest.workspace.path;
     return new DocRenderer(res,
-      new RenderContext(file, repoBaseUrl, path.resolve(pkg.travetto?.docRoot ?? manifest.workspacePath))
+      new RenderContext(file, repoBaseUrl, path.resolve(pkg.travetto?.doc?.root ?? manifest.workspace.path))
     );
   }
 
@@ -56,13 +57,13 @@ export class DocRenderer {
     } else if (isJSXElement(node)) {
       let final: JSXElement = node;
       // Render simple element if needed
-      if (typeof node.type === 'function') {
+      if (typeof node.type === 'function' && node.type !== JSXFragmentType) {
         // @ts-expect-error
         const out = node.type(node.props);
         final = out !== EMPTY_ELEMENT ? out : final;
       }
 
-      if (final.type === createFragment || final.type === JSXFragmentType) {
+      if (final.type === JSXFragmentType) {
         return this.#render(renderer, final.props.children ?? []);
       }
 
@@ -91,7 +92,7 @@ export class DocRenderer {
         case 'bigint':
         case 'boolean': return `${node}`;
         default: {
-          const meta = (typeof node === 'function' ? RootIndex.getFunctionMetadata(node) : undefined);
+          const meta = (typeof node === 'function' ? RuntimeIndex.getFunctionMetadata(node) : undefined);
           if (meta && typeof node === 'function') {
             const title = (await DocFileUtil.isDecorator(node.name, meta.source)) ? `@${node.name}` : node.name;
             const el = this.#support.createElement('CodeLink', {

package/src/util/file.ts

@@ -1,8 +1,9 @@
-import fs from 'fs/promises';
+import fs from 'node:fs/promises';
 
-import { ManifestModuleUtil, path, RootIndex } from '@travetto/manifest';
+import { ManifestModuleUtil, path, RuntimeIndex } from '@travetto/manifest';
 
-const ESLINT_PATTERN = /\s*\/\/ eslint.*$/;
+const ESLINT_PATTERN = /\s*\/\/ eslint.*$/g;
+const ENV_KEY = /Env.([^.]+)[.]key/g;
 
 /**
  * Standard file utilities
@@ -31,7 +32,7 @@ export class DocFileUtil {
     let resolved = path.resolve(file);
     if (!(await fs.stat(resolved).catch(() => false))) {
       if (ManifestModuleUtil.getFileType(file) === 'ts') {
-        resolved = RootIndex.getSourceFile(file);
+        resolved = RuntimeIndex.getSourceFile(file);
       }
       if (!(await fs.stat(resolved).catch(() => false))) {
         throw new Error(`Unknown file to resolve: ${file}`);
@@ -57,12 +58,10 @@ export class DocFileUtil {
       text = await fs.readFile(file, 'utf8');
 
       text = text.split(/\n/)
-        .map(x => {
-          if (ESLINT_PATTERN.test(x)) {
-            x = x.replace(ESLINT_PATTERN, '');
-          }
-          return x;
-        })
+        .map(x => x
+          .replace(ESLINT_PATTERN, '')
+          .replace(ENV_KEY, (_, k) => `'${k}'`)
+        )
         .filter(x => !x.includes('@doc-exclude'))
         .join('\n');
     }

package/src/util/run.ts

@@ -1,8 +1,9 @@
-import os from 'os';
+import os from 'node:os';
+import { spawn, ChildProcess } from 'node:child_process';
 
-import { path, RootIndex } from '@travetto/manifest';
-import { ExecUtil, ExecutionOptions, ExecutionState } from '@travetto/base';
-import { stripAnsiCodes } from '@travetto/terminal';
+import { path, RuntimeIndex, RuntimeContext } from '@travetto/manifest';
+import { Env, ExecUtil } from '@travetto/base';
+import { StyleUtil } from '@travetto/terminal';
 
 export const COMMON_DATE = new Date('2029-03-14T00:00:00.000').getTime();
 
@@ -15,12 +16,6 @@ export type RunConfig = {
   cwd?: string;
 };
 
-type RunState = {
-  cmd: string;
-  args: string[];
-  opts: ExecutionOptions;
-};
-
 class DocState {
   baseline = COMMON_DATE;
   _s = 37;
@@ -50,39 +45,15 @@ class DocState {
 export class DocRunUtil {
   static #docState = new DocState();
 
-  static runState(cmd: string, args: string[], config: RunConfig = {}): RunState {
-    const cwd = config.cwd ?? (config.module ? RootIndex.getModule(config.module)! : RootIndex.mainModule).sourcePath;
-    args = [...args];
-    return {
-      cmd,
-      args,
-      opts: {
-        cwd: path.toPosix(cwd),
-        shell: '/bin/bash',
-        env: {
-          ...process.env,
-          DEBUG: '0',
-          TRV_CAN_RESTART: '0',
-          TRV_CLI_IPC: '',
-          TRV_MANIFEST: '',
-          TRV_BUILD: 'none',
-          TRV_MODULE: config.module ?? '',
-          ...(config.envName ? { TRV_ENV: config.envName } : {}),
-          ...(config.env ?? {})
-        }
-      }
-    };
-  }
-
   /**
    * Clean run output
    */
   static cleanRunOutput(text: string, cfg: RunConfig): string {
-    const cwd = path.toPosix((cfg.module ? RootIndex.getModule(cfg.module)! : RootIndex.mainModule).sourcePath);
-    text = stripAnsiCodes(text.trim())
+    const cwd = path.toPosix((cfg.module ? RuntimeIndex.getModule(cfg.module)! : RuntimeIndex.mainModule).sourcePath);
+    text = StyleUtil.cleanText(text.trim())
       .replaceAll(cwd, '.')
       .replaceAll(os.tmpdir(), '/tmp')
-      .replaceAll(RootIndex.manifest.workspacePath, '<workspace-root>')
+      .replaceAll(RuntimeContext.workspace.path, '<workspace-root>')
       .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}`)
@@ -101,11 +72,25 @@ export class DocRunUtil {
   }
 
   /**
-   * Run process in the background
+   * Spawn command with appropriate environment, and cwd
    */
-  static runBackground(cmd: string, args: string[], config: RunConfig = {}): ExecutionState {
-    const state = this.runState(cmd, args, config);
-    return ExecUtil.spawn(state.cmd, state.args, { ...state.opts, stdio: 'pipe' });
+  static spawn(cmd: string, args: string[], config: RunConfig = {}): ChildProcess {
+    return spawn(cmd, args, {
+      cwd: path.toPosix(config.cwd ?? (config.module ? RuntimeIndex.getModule(config.module)! : RuntimeIndex.mainModule).sourcePath),
+      shell: '/bin/bash',
+      env: {
+        ...process.env,
+        ...Env.DEBUG.export(false),
+        ...Env.TRV_CAN_RESTART.export(false),
+        ...Env.TRV_CLI_IPC.export(undefined),
+        ...Env.TRV_MANIFEST.export(''),
+        ...Env.TRV_BUILD.export('none'),
+        ...Env.TRV_ROLE.export(undefined),
+        ...Env.TRV_MODULE.export(config.module ?? ''),
+        ...(config.envName ? Env.TRV_ENV.export(config.envName) : {}),
+        ...config.env
+      }
+    });
   }
 
   /**
@@ -114,12 +99,12 @@ export class DocRunUtil {
   static async run(cmd: string, args: string[], config: RunConfig = {}): Promise<string> {
     let final: string;
     try {
-      const state = this.runState(cmd, args, config);
-      const res = await ExecUtil.spawn(state.cmd, state.args, { stdio: 'pipe', ...state.opts, catchAsResult: true }).result;
+      const proc = this.spawn(cmd, args, config);
+      const res = await ExecUtil.getResult(proc, { catch: true });
       if (!res.valid) {
         throw new Error(res.stderr);
       }
-      final = stripAnsiCodes(res.stdout.toString()).trim() || stripAnsiCodes(res.stderr.toString()).trim();
+      final = StyleUtil.cleanText(res.stdout).trim() || StyleUtil.cleanText(res.stderr).trim();
     } catch (err) {
       if (err instanceof Error) {
         final = err.message;

package/support/cli.doc.ts

@@ -1,7 +1,8 @@
-import fs from 'fs/promises';
+import fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
 
-import { PackageUtil, path, RootIndex } from '@travetto/manifest';
-import { ExecUtil, CompilerClient, defineEnv } from '@travetto/base';
+import { PackageUtil, path, RuntimeIndex, RuntimeContext } from '@travetto/manifest';
+import { ExecUtil, Env, watchCompiler } from '@travetto/base';
 import { CliCommandShape, CliCommand, CliValidationError, CliUtil } from '@travetto/cli';
 import { MinLength } from '@travetto/schema';
 
@@ -22,18 +23,16 @@ export class DocCommand implements CliCommandShape {
   watch = false;
 
   preMain(): void {
-    Object.assign(process.env, {
-      TRV_CLI_IPC: '',
-      TRV_LOG_PLAIN: 'true',
-      TRV_CONSOLE_WIDTH: '140',
-      FORCE_COLOR: '0',
-    });
-    defineEnv({ debug: false, });
+    Env.DEBUG.set(false);
+    Env.TRV_ROLE.set('doc');
+    Env.TRV_CLI_IPC.clear();
+    Env.TRV_LOG_PLAIN.set(true);
+    Env.FORCE_COLOR.set(false);
   }
 
   preBind(): void {
-    const workspacePkg = PackageUtil.readPackage(RootIndex.manifest.workspacePath);
-    this.outputs = workspacePkg.travetto?.docOutputs ?? ['README.md'];
+    const workspacePkg = PackageUtil.readPackage(RuntimeContext.workspace.path);
+    this.outputs = workspacePkg.travetto?.doc?.outputs ?? ['README.md'];
   }
 
   preHelp(): void {
@@ -53,20 +52,22 @@ export class DocCommand implements CliCommandShape {
     }
 
     const args = process.argv.slice(2).filter(x => !/(-w|--watch)/.test(x));
-    await new CompilerClient().onFileChange(async ({ action, file }) => {
+    for await (const { action, file } of watchCompiler({ restartOnExit: true })) {
       if (action === 'update' && file === this.input) {
-        await ExecUtil.spawn('npx', ['trv', ...args], {
-          cwd: RootIndex.mainModule.sourcePath,
-          env: { TRV_QUIET: '1' },
-          stdio: 'inherit', catchAsResult: true
+        const proc = spawn('npx', ['trv', ...args], {
+          cwd: RuntimeIndex.mainModule.sourcePath,
+          shell: false,
+          env: { ...process.env, ...Env.TRV_QUIET.export(true) },
+          stdio: 'inherit'
         });
+        await ExecUtil.getResult(proc, { catch: true });
       }
-    }, true);
+    }
   }
 
   async render(): Promise<void> {
     const { DocRenderer } = await import('../src/render/renderer.js');
-    const ctx = await DocRenderer.get(this.input, RootIndex.manifest);
+    const ctx = await DocRenderer.get(this.input, RuntimeContext);
     const outputs = this.outputs.map(output =>
       output.includes('.') ? [path.extname(output).replace('.', ''), path.resolve(output)] :
         [output, null] as const