@travetto/doc 3.4.2 → 4.0.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/doc",
-  "version": "3.4.2",
+  "version": "4.0.0-rc.0",
   "description": "Documentation support for the Travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,13 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/base": "^3.4.1",
+    "@travetto/base": "^4.0.0-rc.0",
+    "@travetto/terminal": "^4.0.0-rc.0",
     "@types/prismjs": "^1.26.3",
     "prismjs": "^1.29.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^3.4.6"
+    "@travetto/cli": "^4.0.0-rc.0"
   },
   "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' },

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,15 @@ 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;
+  static async get(file: string, manifest: ManifestContext): Promise<DocRenderer> {
+    const mod = RuntimeIndex.getFromSource(file)?.import;
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     const res = await import(mod!) as DocumentShape;
 
-    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))
     );
   }
 
@@ -62,7 +61,7 @@ export class DocRenderer {
         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 +90,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,8 @@
-import os from 'os';
+import os from 'node:os';
 
-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, ExecutionOptions, ExecutionState } from '@travetto/base';
+import { StyleUtil } from '@travetto/terminal';
 
 export const COMMON_DATE = new Date('2029-03-14T00:00:00.000').getTime();
 
@@ -51,7 +51,7 @@ 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;
+    const cwd = config.cwd ?? (config.module ? RuntimeIndex.getModule(config.module)! : RuntimeIndex.mainModule).sourcePath;
     args = [...args];
     return {
       cmd,
@@ -61,13 +61,14 @@ export class DocRunUtil {
         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 } : {}),
+          ...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 ?? {})
         }
       }
@@ -78,11 +79,11 @@ export class DocRunUtil {
    * 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}`)
@@ -119,7 +120,7 @@ export class DocRunUtil {
       if (!res.valid) {
         throw new Error(res.stderr);
       }
-      final = stripAnsiCodes(res.stdout.toString()).trim() || stripAnsiCodes(res.stderr.toString()).trim();
+      final = StyleUtil.cleanText(res.stdout.toString()).trim() || StyleUtil.cleanText(res.stderr.toString()).trim();
     } catch (err) {
       if (err instanceof Error) {
         final = err.message;

package/support/cli.doc.ts

@@ -1,7 +1,7 @@
-import fs from 'fs/promises';
+import fs from 'node:fs/promises';
 
-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 +22,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 +51,20 @@ export class DocCommand implements CliCommandShape {
     }
 
     const args = process.argv.slice(2).filter(x => !/(-w|--watch)/.test(x));
-    await new CompilerClient().onFileChange(async ({ action, file }) => {
+    await watchCompiler(async ({ action, file }) => {
       if (action === 'update' && file === this.input) {
         await ExecUtil.spawn('npx', ['trv', ...args], {
-          cwd: RootIndex.mainModule.sourcePath,
-          env: { TRV_QUIET: '1' },
+          cwd: RuntimeIndex.mainModule.sourcePath,
+          env: { ...Env.TRV_QUIET.export(true) },
           stdio: 'inherit', catchAsResult: true
         });
       }
-    }, true);
+    }, { restartOnExit: 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