@travetto/doc 3.0.3 → 3.1.0-rc.0

package/README.md

@@ -93,13 +93,13 @@ The run command allows for generating documentation output.
 ```bash
 $ trv doc --help
 
-Usage:  doc [options]
+Usage: doc [options]
 
 Options:
-  -i, --input <input>      Input File (default: "DOC.tsx")
-  -o, --outputs <outputs>  Outputs (default: [])
-  -w, --watch              Watch
-  -h, --help               display help for command
+  -i, --input <string>    Input File (default: "DOC.tsx")
+  -o, --outputs <string>  Outputs (default: [])
+  -w, --watch             Watch? (default: false)
+  -h, --help              display help for command
 ```
 
 By default, running the command will output the [Markdown](https://en.wikipedia.org/wiki/Markdown) content directly to the terminal.
@@ -151,13 +151,7 @@ Sample documentation for fictional module.  This module fictitiously relies upon
 
 Usage:  <span class="token punctuation">[</span>options<span class="token punctuation">]</span> <span class="token punctuation">[</span>command<span class="token punctuation">]</span>
 
-Options:
-  -V, <span class="token parameter variable">--version</span>                  output the version number
-  -h, <span class="token parameter variable">--help</span>                     display <span class="token builtin class-name">help</span> <span class="token keyword">for</span> <span class="token builtin class-name">command</span>
-
 Commands:
-  doc <span class="token punctuation">[</span>options<span class="token punctuation">]</span>
-  main <span class="token operator">&lt;</span>fileOrImport<span class="token operator">></span> <span class="token punctuation">[</span>args<span class="token punctuation">..</span>.<span class="token punctuation">]</span>
-  <span class="token builtin class-name">help</span> <span class="token punctuation">[</span>command<span class="token punctuation">]</span>                 display <span class="token builtin class-name">help</span> <span class="token keyword">for</span> <span class="token builtin class-name">command</span></code></pre>
+  doc          Command line support <span class="token keyword">for</span> generating module docs.</code></pre>
   </figure>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/doc",
-  "version": "3.0.3",
+  "version": "3.1.0-rc.0",
   "description": "Documentation support for the Travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,12 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/base": "^3.0.3",
+    "@travetto/base": "^3.1.0-rc.0",
     "@types/prismjs": "^1.26.0",
     "prismjs": "^1.29.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^3.0.3"
+    "@travetto/cli": "^3.1.0-rc.0"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/mapping/mod-mapping.ts

@@ -1,8 +1,4 @@
 export const MOD_MAPPING = {
-  App: {
-    name: '@travetto/app', folder: '@travetto/app', displayName: 'Application',
-    description: 'Application registration/management and run support.'
-  },
   Asset: {
     name: '@travetto/asset', folder: '@travetto/asset', displayName: 'Asset',
     description: 'Modular library for storing and retrieving binary assets'

package/src/util/run.ts

@@ -49,12 +49,13 @@ 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(config.cwd ?? path.cwd()),
+        cwd: path.toPosix(cwd),
         shell: '/bin/bash',
         env: {
           ...process.env,
@@ -73,9 +74,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())
-      .replace(new RegExp(path.cwd(), 'g'), '.')
+      .replaceAll(cwd, '.')
       .replaceAll(RootIndex.manifest.workspacePath, '<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}`)
       .replace(/^(.{1,4})?Compiling[.]*/, '') // Compiling message, remove

package/support/cli.doc.ts

@@ -1,30 +1,25 @@
 import fs from 'fs/promises';
 
-import { PackageUtil, path, RootIndex, watchFolderImmediate } from '@travetto/manifest';
+import { PackageUtil, path, RootIndex, watchFolders } from '@travetto/manifest';
 import { ExecUtil, GlobalEnvConfig } from '@travetto/base';
-import { CliCommand, OptionConfig, ListOptionConfig } from '@travetto/cli';
-
-import { DocRenderer } from '../src/render/renderer';
-
-type Options = {
-  input: OptionConfig<string>;
-  outputs: ListOptionConfig<string>;
-  watch: OptionConfig<boolean>;
-};
+import { CliCommandShape, CliCommand, CliValidationError } from '@travetto/cli';
+import { MinLength } from '@travetto/schema';
 
 /**
  * Command line support for generating module docs.
  */
-export class DocCommand extends CliCommand<Options> {
-  name = 'doc';
+@CliCommand()
+export class DocCommand implements CliCommandShape {
 
-  getOptions(): Options {
-    return {
-      input: this.option({ desc: 'Input File', def: 'DOC.tsx' }),
-      outputs: this.listOption({ desc: 'Outputs', def: [] }),
-      watch: this.boolOption({ desc: 'Watch' })
-    };
-  }
+  /** Input File */
+  input = 'DOC.tsx';
+
+  /** Outputs */
+  @MinLength(1)
+  outputs: string[] = [];
+
+  /** Watch? */
+  watch = false;
 
   envInit(): GlobalEnvConfig {
     return {
@@ -38,52 +33,60 @@ export class DocCommand extends CliCommand<Options> {
     };
   }
 
-  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) {
+  finalize(): void {
+    if (this.outputs.length === 0) {
       const workspacePkg = PackageUtil.readPackage(RootIndex.manifest.workspacePath);
-      this.cmd.outputs = workspacePkg.travetto?.docOutputs ?? ['README.md'];
+      this.outputs = workspacePkg.travetto?.docOutputs ?? ['README.md'];
     }
+    this.input = path.resolve(this.input);
+  }
 
-    const outputs = this.cmd.outputs.map(output =>
-      output.includes('.') ? [path.extname(output).substring(1), path.resolve(output)] :
-        [output, null] as const
-    );
+  async validate(...args: unknown[]): Promise<CliValidationError | undefined> {
+    const docFile = path.resolve(this.input);
+    if (!(await fs.stat(docFile).catch(() => false))) {
+      return {
+        kind: 'required',
+        path: 'input',
+        message: `The input ${this.input} does not exist`
+      };
+    }
+  }
 
-    if (this.cmd.watch) {
-      const args = process.argv.slice(2).filter(x => !x.startsWith('-w') && !x.startsWith('--w'));
-      await watchFolderImmediate(path.dirname(docFile),
-        () => ExecUtil.spawn('npx', ['trv', ...args], {
+  async runWatch(): Promise<void> {
+    const args = process.argv.slice(2).filter(x => !/(-w|--watch)/.test(x));
+    const stream = watchFolders([{ src: path.dirname(this.input), immediate: true }]);
+    for await (const { action, file } of stream) {
+      if (action === 'update' && file === this.input) {
+        await 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,
-        persistent: true
-      });
+        });
+      }
     }
+  }
 
-    try {
-      const ctx = await DocRenderer.get(docFile, RootIndex.manifest);
+  async render(): Promise<void> {
+    const { DocRenderer } = await import('../src/render/renderer.js');
+    const ctx = await DocRenderer.get(this.input, RootIndex.manifest);
+    const outputs = this.outputs.map(output =>
+      output.includes('.') ? [path.extname(output).substring(1), path.resolve(output)] :
+        [output, null] as const
+    );
 
-      for (const [fmt, out] of outputs) {
-        const result = await ctx.render(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);
-        }
+    for (const [fmt, out] of outputs) {
+      const result = await ctx.render(fmt);
+      if (out) {
+        const finalName = path.resolve(out);
+        await fs.writeFile(finalName, result, 'utf8');
+        console.log(`Wrote docs ${this.input}: ${finalName}`);
+      } else {
+        process.stdout.write(result);
       }
-    } catch (err) {
-      console.error(err);
-      this.exit(1);
     }
   }
+
+  main(): Promise<void> {
+    return this.watch ? this.runWatch() : this.render();
+  }
 }