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

package/src/util/run.ts

@@ -1,11 +1,17 @@
 import { spawnSync } from 'child_process';
 
-import { PathUtil, ExecUtil, EnvUtil, ExecutionOptions, ExecutionState } from '@travetto/boot';
+import { path, RootIndex } from '@travetto/manifest';
+import { ExecUtil, ExecutionOptions, ExecutionState } from '@travetto/base';
+import { stripAnsiCodes } from '@travetto/terminal';
+
+export const COMMON_DATE = new Date('2029-03-14T00:00:00.000').getTime();
 
 export type RunConfig = {
   filter?: (line: string) => boolean;
-  module?: 'base' | 'boot';
+  rewrite?: (text: string) => string;
+  module?: string;
   env?: Record<string, string>;
+  profiles?: string[];
   cwd?: string;
 };
 
@@ -16,7 +22,7 @@ type RunState = {
 };
 
 class DocState {
-  baseline = new Date(`${new Date().getFullYear()}-03-14T00:00:00.000`).getTime();
+  baseline = COMMON_DATE;
   _s = 37;
   ids: Record<string, string> = {};
 
@@ -46,21 +52,19 @@ 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',
+          ...process.env,
+          DEBUG: '0',
+          TRV_MANIFEST: '',
+          TRV_BUILD: 'warn',
+          TRV_MODULE: config.module ?? '',
+          ...(config.profiles ? { TRV_PROFILES: config.profiles.join(' ') } : {}),
           ...(config.env ?? {})
         }
       }
@@ -71,18 +75,20 @@ 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'), '.')
-      .replace(/([.]trv_cache)[_A-Za-z0-9]+/g, (_, b) => b)
+    text = stripAnsiCodes(text.trim())
+      .replace(new RegExp(path.cwd(), 'g'), '.')
+      .replaceAll(RootIndex.manifest.workspacePath, '<workspace-root>')
+      .replace(/^(.{1,4})?Compiling[.]*/, '') // Compiling message, remove
+      .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(/(\d+[.]\d+[.]\d+)-(alpha|rc)[.]\d+/g, (all, v) => v);
     if (cfg.filter) {
       text = text.split(/\n/g).filter(cfg.filter).join('\n');
     }
+    if (cfg.rewrite) {
+      text = cfg.rewrite(text);
+    }
     return text;
   }
 
@@ -104,17 +110,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, watchFolders } from '@travetto/manifest';
+import { 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>;
+};
+
+/**
+ * Command line support for generating module docs.
+ */
+export class DocCommand extends CliCommand<Options> {
+  name = 'doc';
+
+  getOptions(): Options {
+    const input = RootIndex.mainModule.files['doc']?.find(x => x.sourceFile.endsWith('DOC.ts'));
+    return {
+      input: this.option({ desc: 'Input File', def: input?.relativeFile ?? 'DOC.ts' }),
+      outputs: this.listOption({ desc: 'Outputs', def: [] }),
+      watch: this.boolOption({ desc: 'Watch' })
+    };
+  }
+
+  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))) {
+      console.error(`The input ${this.cmd.input} does not exist`);
+      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 => output.includes('.') ? [path.extname(output).substring(1), path.resolve(output)] : [output, null] as const);
+
+    if (this.cmd.watch) {
+      const args = process.argv.slice(2).filter(x => !x.startsWith('-w') && !x.startsWith('--w'));
+      await watchFolders([path.dirname(docFile)],
+        () => ExecUtil.spawn('npx', ['trv', ...args], {
+          cwd: RootIndex.mainModule.sourcePath,
+          env: { TRV_QUIET: '1' },
+          stdio: 'inherit', catchAsResult: true
+        }), {
+        filter: ev => ev.action === 'update' && ev.file === docFile
+      });
+    }
+
+    try {
+      for (const [fmt, out] of outputs) {
+        const result = await RenderUtil.render(docFile, fmt);
+        if (out) {
+          const finalName = path.resolve(out);
+          await fs.writeFile(finalName, result, 'utf8');
+          console.log(`Wrote docs ${this.cmd.input}: ${finalName}`);
+        } else {
+          process.stdout.write(result);
+        }
+      }
+    } catch (err) {
+      console.error(err);
+      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));
-    }
-  }
-}