@travetto/doc 3.0.0-rc.2 → 3.0.0-rc.5

package/src/util/resolve.ts

@@ -1,4 +1,3 @@
-import { FsUtil } from '@travetto/boot';
 import { FileUtil } from './file';
 
 /**
@@ -9,26 +8,20 @@ export class ResolveUtil {
   static resolveRef<T>(title: string | T, file: string): { title: string | T, file: string, line: number } {
 
     let line = 0;
-    const { resolved } = FileUtil.resolveFile(file);
-    file = resolved;
+    const res = FileUtil.read(file);
+    file = res.file;
 
-    if (!FsUtil.existsSync(file)) {
-      throw new Error(`${file} is not a valid location`);
-    } else {
-      const res = FileUtil.read(file);
-      file = res.file;
-      if (typeof title == 'string') {
-        if (res.content) {
-          line = res.content.split(/\n/g)
-            .findIndex(x => new RegExp(`(class|function)[ ]+${title}`).test(x));
-          if (line < 0) {
-            line = 0;
-          } else {
-            line += 1;
-          }
-          if (FileUtil.isDecorator(title, file)) {
-            title = `@${title}`;
-          }
+    if (typeof title == 'string') {
+      if (res.content) {
+        line = res.content.split(/\n/g)
+          .findIndex(x => new RegExp(`(class|function)[ ]+${title}`).test(x));
+        if (line < 0) {
+          line = 0;
+        } else {
+          line += 1;
+        }
+        if (FileUtil.isDecorator(title, file)) {
+          title = `@${title}`;
         }
       }
     }

package/src/util/run.ts

@@ -1,10 +1,12 @@
 import { spawnSync } from 'child_process';
 
-import { PathUtil, ExecUtil, EnvUtil, ExecutionOptions, ExecutionState } from '@travetto/boot';
+import { path } from '@travetto/manifest';
+import { Env, ExecUtil, ExecutionOptions, ExecutionState } from '@travetto/base';
+import { stripAnsiCodes } from '@travetto/terminal';
 
 export type RunConfig = {
   filter?: (line: string) => boolean;
-  module?: 'base' | 'boot';
+  module?: string;
   env?: Record<string, string>;
   cwd?: string;
 };
@@ -16,7 +18,7 @@ type RunState = {
 };
 
 class DocState {
-  baseline = new Date(`${new Date().getFullYear()}-03-14T00:00:00.000`).getTime();
+  baseline = new Date('2029-03-14T00:00:00.000').getTime();
   _s = 37;
   ids: Record<string, string> = {};
 
@@ -46,21 +48,16 @@ export class DocRunUtil {
 
   static runState(cmd: string, args: string[], config: RunConfig = {}): RunState {
     args = [...args];
-    if (cmd.endsWith('.ts')) {
-      const mod = config.module ?? 'base';
-      args.unshift(require.resolve(`@travetto/${mod}/bin/main`), cmd);
-      cmd = process.argv0;
-    }
     return {
       cmd,
       args,
       opts: {
-        cwd: config.cwd ?? PathUtil.cwd,
+        cwd: path.toPosix(config.cwd ?? path.cwd()),
         shell: '/bin/bash',
         env: {
-          ...EnvUtil.getAll(),
-          DEBUG: '',
-          TRV_DEBUG: '0',
+          ...Env.export(/^(TRV_.*|NODE_.*|.*COLOR.*|PATH)$/),
+          DEBUG: '0',
+          ...(config.module ? { TRV_MANIFEST: config.module } : {}),
           ...(config.env ?? {})
         }
       }
@@ -71,11 +68,10 @@ export class DocRunUtil {
    * Clean run output
    */
   static cleanRunOutput(text: string, cfg: RunConfig): string {
-    text = text.trim()
-      // eslint-disable-next-line no-control-regex
-      .replace(/\x1b\[[?]?[0-9]{1,2}[a-z]/gi, '')
-      .replace(/[A-Za-z0-9_.\-\/\\]+\/travetto\/module\//g, '@trv:')
-      .replace(new RegExp(PathUtil.cwd, 'g'), '.')
+    text = stripAnsiCodes(text.trim())
+      .replace(/^(.{1,4})?Compiling[.]*/, '') // Compiling message, remove
+      .replace(/[A-Za-z0-9_.\-\/\\]+\/travetto\/module\//g, '@travetto/')
+      .replace(new RegExp(path.cwd(), 'g'), '.')
       .replace(/([.]trv_cache)[_A-Za-z0-9]+/g, (_, b) => b)
       .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))
@@ -104,17 +100,19 @@ export class DocRunUtil {
     let final: string;
     try {
       const state = this.runState(cmd, args, config);
-      const res = spawnSync(state.cmd, state.args, {
+      const spawnCfg = {
         ...state.opts,
         stdio: 'pipe' as const,
         encoding: 'utf8',
         maxBuffer: 1024 * 1024 * 20,
-      });
+      } as const;
+
+      const res = spawnSync(state.cmd, state.args, spawnCfg);
 
       if (res.error) {
         throw res.error;
       }
-      final = res.stdout.toString() || res.stderr.toString();
+      final = stripAnsiCodes(res.stdout.toString()).trim() || stripAnsiCodes(res.stderr.toString()).trim();
     } catch (err) {
       if (err instanceof Error) {
         console.log('Found!', cmd, args, '\n', err);

package/support/cli.doc.ts

@@ -0,0 +1,84 @@
+import fs from 'fs/promises';
+
+import { PackageUtil, path, RootIndex } from '@travetto/manifest';
+import { WatchUtil, ExecUtil, GlobalEnvConfig } from '@travetto/base';
+import { CliCommand, OptionConfig, ListOptionConfig } from '@travetto/cli';
+
+import { RenderUtil } from '../src/render/util';
+
+type Options = {
+  input: OptionConfig<string>;
+  outputs: ListOptionConfig<string>;
+  watch: OptionConfig<boolean>;
+  stdout: OptionConfig<boolean>;
+};
+
+/**
+ * Command line support for generating module docs.
+ */
+export class DocCommand extends CliCommand<Options> {
+  name = 'doc';
+
+  getOptions(): Options {
+    return {
+      input: this.option({ desc: 'Input File', def: 'DOC.ts' }),
+      outputs: this.listOption({ desc: 'Outputs', def: [] }),
+      watch: this.boolOption({ desc: 'Watch' }),
+      stdout: this.boolOption({ desc: 'Write to stdout', def: false })
+    };
+  }
+
+  envInit(): GlobalEnvConfig {
+    return {
+      debug: false,
+      set: {
+        TRV_CONSOLE_WIDTH: 140,
+        TRV_CLI_IPC: '',
+        FORCE_COLOR: 0,
+        TRV_LOG_PLAIN: true
+      }
+    };
+  }
+
+  async action(): Promise<void> {
+    const docFile = path.resolve(this.cmd.input);
+    if (!(await fs.stat(docFile).catch(() => false))) {
+      ExecUtil.returnResponse(`The input ${this.cmd.input} does not exist`, true);
+      return this.exit(1);
+    }
+
+    if (this.cmd.outputs.length === 0) {
+      const workspacePkg = PackageUtil.readPackage(RootIndex.manifest.workspacePath);
+      this.cmd.outputs = workspacePkg.travetto?.docOutputs ?? ['README.md'];
+    }
+
+    const outputs = this.cmd.outputs.map(output => [path.extname(output).substring(1), path.resolve(output)]);
+
+    // If specifying output
+    const write = async (): Promise<void> => {
+      RenderUtil.purge(docFile);
+      for (const [fmt, out] of outputs) {
+        const finalName = path.resolve(out);
+        const result = await RenderUtil.render(docFile, fmt);
+        if (this.cmd.stdout) {
+          process.stdout.write(result);
+        } else {
+          await fs.writeFile(finalName, result, 'utf8');
+        }
+      }
+    };
+
+    if (this.cmd.watch) {
+      await WatchUtil.watchFile(docFile, write);
+    } else {
+      try {
+        await write();
+        ExecUtil.returnResponse(`Wrote docs for ${this.cmd.input}`);
+        return this.exit(0);
+      } catch (err) {
+        ExecUtil.returnResponse(`${err}`, true);
+        return this.exit(1);
+      }
+    }
+  }
+}

package/bin/cli-doc.ts

@@ -1,84 +0,0 @@
-import * as path from 'path';
-import * as fs from 'fs/promises';
-
-import { CliCommand, OptionConfig, ListOptionConfig } from '@travetto/cli/src/command';
-import { EnvInit } from '@travetto/base/bin/init';
-import { PathUtil } from '@travetto/boot';
-
-type Options = {
-  input: OptionConfig<string>;
-  output: ListOptionConfig<string>;
-  format: OptionConfig<string>;
-  watch: OptionConfig<boolean>;
-};
-
-/**
- * Command line support for generating module docs.
- */
-export class DocCommand extends CliCommand<Options> {
-  name = 'doc';
-
-  getOptions(): Options {
-    return {
-      input: this.option({ desc: 'Input File', def: 'doc.ts' }),
-      output: this.listOption({ desc: 'Output files' }),
-      format: this.option({ desc: 'Format', def: 'md' }),
-      watch: this.boolOption({ desc: 'Watch' })
-    };
-  }
-
-  async envInit(): Promise<void> {
-    EnvInit.init({
-      debug: '0',
-      append: {
-        TRV_SRC_LOCAL: 'doc',
-        TRV_RESOURCES: 'doc/resources'
-      },
-      set: {
-        TRV_CONSOLE_WIDTH: '140',
-        TRV_CLI_JSON_IPC: '',
-        TRV_COLOR: '0',
-        TRV_LOG_PLAIN: '1'
-      }
-    });
-  }
-
-  async action(): Promise<void> {
-    console.error(process.env);
-
-    const { PhaseManager } = await import('@travetto/base');
-    // Standard compile
-    await PhaseManager.run('init');
-
-    const { RenderUtil } = await import('../src/render/util');
-
-    const docFile = PathUtil.resolveUnix(this.cmd.input);
-
-    // If specifying output
-    if (this.cmd.output.length) {
-      const write = async (): Promise<void> => {
-        RenderUtil.purge(docFile);
-        for (const out of this.cmd.output) {
-          const fmt = path.extname(out) ?? this.cmd.format;
-          const finalName = await PathUtil.resolveUnix(out);
-          const result = await RenderUtil.render(docFile, fmt);
-          await fs.writeFile(finalName, result, 'utf8');
-        }
-      };
-
-      if (this.cmd.watch) {
-        const { WatchUtil } = await import('@travetto/watch');
-        await WatchUtil.watchFile(docFile, write, true);
-      } else {
-        try {
-          await write();
-        } catch (err) {
-          console.error(PathUtil.cwd, err);
-          process.exit(1);
-        }
-      }
-    } else {
-      console.log(await RenderUtil.render(docFile, this.cmd.format));
-    }
-  }
-}