@travetto/doc 3.0.0-rc.20 → 3.0.0-rc.22

package/README.md

@@ -1,11 +1,15 @@
 <!-- This file was generated by @travetto/doc and should not be modified directly -->
 <!-- Please modify https://github.com/travetto/travetto/tree/main/module/doc/DOC.ts and execute "npx trv doc" to rebuild -->
 # Documentation
-## Documentation support for the travetto framework
+## Documentation support for the Travetto framework
 
 **Install: @travetto/doc**
 ```bash
 npm install @travetto/doc
+
+# or
+
+yarn add @travetto/doc
 ```
 
 This module provides the ability to generate documentation in [HTML](https://en.wikipedia.org/wiki/HTML) and/or [Markdown](https://en.wikipedia.org/wiki/Markdown).  The module relies on integrating with the source of the project, and providing a fully referenced code-base.  This allows for automatic updates when code is changed and/or refactored. 
@@ -62,7 +66,7 @@ As you can see, you need to export a field named `text` as the body of the help
    *  `Header` - Standard header
    *  `Image` - Image reference
    *  `Input` - Input text
-   *  `Install` - NPM Installation
+   *  `Install` - Installing a package or program
    *  `Item` - List item
    *  `Library` - Library reference
    *  `List` - Standard List
@@ -78,6 +82,7 @@ As you can see, you need to export a field named `text` as the body of the help
    *  `SnippetLink` - Link to a snippet of code, including line number
    *  `Strong` - Strong Content
    *  `SubSection` - Sub-section
+   *  `SubSubSection` - Sub-sub-section
    *  `Table` - Table
    *  `TableOfContents` - Table Of Contents
    *  `Terminal` - Terminal output
@@ -115,7 +120,7 @@ By default, running the command will output the [Markdown](https://en.wikipedia.
 $ trv doc -o html
 
 <!-- This file was generated by @travetto/doc and should not be modified directly -->
-<!-- Please modify @travetto/doc/doc-exec/DOC.ts and execute "npx trv doc" to rebuild -->
+<!-- Please modify ./doc-exec/DOC.ts and execute "npx trv doc" to rebuild -->
 <h1>@travetto-doc/doc
           
         </h1>
@@ -124,7 +129,11 @@ $ trv doc -o html
       <figcaption class="install">Install @travetto-doc/doc
       
       </figcaption>
-      <pre><code class="language-bash"><span class="token function">npm</span> <span class="token function">install</span> @travetto-doc/doc</code></pre>     
+      <pre><code class="language-bash"><span class="token function">npm</span> <span class="token function">install</span> @travetto-doc/doc
+
+<span class="token comment"># or</span>
+
+<span class="token function">yarn</span> <span class="token function">add</span> @travetto-doc/doc</code></pre>     
       </figure>
 
 Sample documentation for fictional module.  This module fictitiously relies upon <a class="module-link" href="https://github.com/travetto/travetto/tree/main/module/cache" title="Caching functionality with decorators for declarative use.">Caching</a> functionality.
@@ -137,7 +146,7 @@ Sample documentation for fictional module.  This module fictitiously relies upon
 
       <figure class="code">
       <figcaption class="code">Document Sample
-      <cite><a target="_blank" href="@travetto/doc/doc-exec/src/test.ts">Source</a></cite>
+      <cite><a target="_blank" href="./doc-exec/src/test.ts">Source</a></cite>
       </figcaption>
       <pre><code class="language-typescript"><span class="token keyword">class</span> <span class="token class-name">TestFile</span> <span class="token punctuation">{{'{'}}</span>
   <span class="token keyword">static</span> <span class="token function">method</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token keyword">void</span> <span class="token punctuation">{{'{'}}</span> <span class="token punctuation">{{'}'}}</span>
@@ -163,5 +172,4 @@ Commands:
   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>     
       </figure>
-Wrote docs for DOC.ts
 ```

package/package.json

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

package/src/lib.ts

@@ -6,8 +6,18 @@ const { Library } = node;
 export const lib = {
   Travetto: Library('Travetto', 'https://travetto.dev'),
   Typescript: Library('Typescript', 'https://typescriptlang.org'),
+  Javascript: Library('Javascript', 'https://developer.mozilla.org/en-US/docs/Web/JavaScript'),
   Node: Library('Node', 'https://nodejs.org'),
   TravettoPlugin: Library('VSCode plugin', 'https://marketplace.visualstudio.com/items?itemName=arcsine.travetto-plugin'),
+  Npm: Library('Npm', 'https://docs.npmjs.com/downloading-and-installing-node-js-and-npm'),
+  Yarn: Library('Yarn', 'https://yarnpg.com'),
+  Eslint: Library('ESLint', 'https://eslint.org/'),
+  Rollup: Library('Rollup', 'https://rollupjs.org/'),
+
+  // Module
+  CommonJS: Library('CommonJS', 'https://nodejs.org/api/modules.html'),
+  EcmascriptModule: Library('Ecmascript Module', 'https://nodejs.org/api/esm.html'),
+  PackageJson: Library('Package JSON', 'https://docs.npmjs.com/cli/v9/configuring-npm/package-json'),
 
   // Download
   NodeDownload: Library('Node', 'https://nodejs.org/en/download/current/'),
@@ -29,11 +39,14 @@ export const lib = {
   JSDoc: Library('JSDoc', 'http://usejsdoc.org/about-getting-started.html'),
   CodeLens: Library('CodeLens',
     'https://code.visualstudio.com/api/language-extensions/programmatic-language-features#codelens-show-actionable-context-information-within-source-code'),
+  ORM: Library('Object Relationship Mapping', 'https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping'),
+  UUID: Library('UUID', 'https://en.wikipedia.org/wiki/Universally_unique_identifier'),
 
   // Node
   ChildProcess: Library('child_process', 'https://nodejs.org/api/child_process.html'),
   AsyncHooks: Library('async_hooks', 'https://nodejs.org/api/async_hooks.html'),
   Http: Library('http', 'https://nodejs.org/api/http.html'),
+  Path: Library('http', 'https://nodejs.org/api/path.html'),
   Https: Library('https', 'https://nodejs.org/api/https.html'),
   Console: Library('console', 'https://nodejs.org/api/console.html'),
   Assert: Library('assert', 'https://nodejs.org/api/assert.html'),
@@ -49,11 +62,12 @@ export const lib = {
   OpenAPIGenerator: Library('OpenAPI client generation tools', 'https://github.com/OpenAPITools/openapi-generator'),
   Gaze: Library('gaze', 'https://github.com/shama/gaze'),
   Chokidar: Library('chokidar', 'https://github.com/paulmillr/chokidar'),
-  Faker: Library('faker', 'https://github.com/marak/Faker.js/'),
+  Faker: Library('faker', 'https://github.com/faker-js/faker'),
   Yeoman: Library('yeoman', 'http://yeoman.io'),
   Commander: Library('commander', 'https://www.npmjs.com/package/commander'),
   Curl: Library('curl', 'https://curl.haxx.se/'),
   Fetch: Library('fetch', 'https://www.npmjs.com/package/node-fetch'),
+  ParcelWatcher: Library('fetch', 'https://www.npmjs.com/package/@parcel/watcher'),
 
   // JWT
   JWT: Library('JWT', 'https://jwt.io/'),
@@ -83,7 +97,6 @@ export const lib = {
   Firestore: Library('Firestore', 'https://firebase.google.com/docs/firestore'),
   SQLite: Library('SQLite', 'https://www.sqlite.org/'),
 
-
   // Rest
   Express: Library('express', 'https://expressjs.com'),
   Passport: Library('passport', 'http://passportjs.org'),

package/src/mod-mapping.ts

@@ -13,31 +13,31 @@ export const MOD_MAPPING = {
   },
   Auth: {
     name:'@travetto/auth', folder:'@travetto/auth', displayName: 'Authentication',
-    description: 'Authentication scaffolding for the travetto framework'
+    description: 'Authentication scaffolding for the Travetto framework'
   },
   AuthModel: {
     name:'@travetto/auth-model', folder:'@travetto/auth-model', displayName: 'Authentication Model',
-    description: 'Authentication model support for the travetto framework'
+    description: 'Authentication model support for the Travetto framework'
   },
   AuthRest: {
     name:'@travetto/auth-rest', folder:'@travetto/auth-rest', displayName: 'Rest Auth',
-    description: 'Rest authentication integration support for the travetto framework'
+    description: 'Rest authentication integration support for the Travetto framework'
   },
   AuthRestContext: {
     name:'@travetto/auth-rest-context', folder:'@travetto/auth-rest-context', displayName: 'Rest Auth Context',
-    description: 'Rest authentication context integration support for the travetto framework'
+    description: 'Rest authentication context integration support for the Travetto framework'
   },
   AuthRestJwt: {
     name:'@travetto/auth-rest-jwt', folder:'@travetto/auth-rest-jwt', displayName: 'Rest Auth JWT',
-    description: 'Rest authentication JWT integration support for the travetto framework'
+    description: 'Rest authentication JWT integration support for the Travetto framework'
   },
   AuthRestPassport: {
     name:'@travetto/auth-rest-passport', folder:'@travetto/auth-rest-passport', displayName: 'Rest Auth Passport',
-    description: 'Rest authentication integration support for the travetto framework'
+    description: 'Rest authentication integration support for the Travetto framework'
   },
   AuthRestSession: {
     name:'@travetto/auth-rest-session', folder:'@travetto/auth-rest-session', displayName: 'Rest Auth Session',
-    description: 'Rest authentication session integration support for the travetto framework'
+    description: 'Rest authentication session integration support for the Travetto framework'
   },
   Base: {
     name:'@travetto/base', folder:'@travetto/base', displayName: 'Base',
@@ -49,7 +49,7 @@ export const MOD_MAPPING = {
   },
   Cli: {
     name:'@travetto/cli', folder:'@travetto/cli', displayName: 'Command Line Interface',
-    description: 'CLI infrastructure for travetto framework'
+    description: 'CLI infrastructure for Travetto framework'
   },
   Command: {
     name:'@travetto/command', folder:'@travetto/command', displayName: 'Command',
@@ -57,7 +57,7 @@ export const MOD_MAPPING = {
   },
   Compiler: {
     name:'@travetto/compiler', folder:'@travetto/compiler', displayName: 'Compiler',
-    description: 'Compiler'
+    description: 'The compiler infrastructure for the Travetto framework'
   },
   Config: {
     name:'@travetto/config', folder:'@travetto/config', displayName: 'Configuration',
@@ -73,7 +73,7 @@ export const MOD_MAPPING = {
   },
   Doc: {
     name:'@travetto/doc', folder:'@travetto/doc', displayName: 'Documentation',
-    description: 'Documentation support for the travetto framework'
+    description: 'Documentation support for the Travetto framework'
   },
   Email: {
     name:'@travetto/email', folder:'@travetto/email', displayName: 'Email',
@@ -105,7 +105,7 @@ export const MOD_MAPPING = {
   },
   Manifest: {
     name:'@travetto/manifest', folder:'@travetto/manifest', displayName: 'Manifest',
-    description: 'Manifest support'
+    description: 'Support for project indexing, manifesting, along with file watching'
   },
   Model: {
     name:'@travetto/model', folder:'@travetto/model', displayName: 'Data Modeling Support',
@@ -157,7 +157,7 @@ export const MOD_MAPPING = {
   },
   Openapi: {
     name:'@travetto/openapi', folder:'@travetto/openapi', displayName: 'OpenAPI Specification',
-    description: 'OpenAPI integration support for the travetto framework'
+    description: 'OpenAPI integration support for the Travetto framework'
   },
   Overview: {
     name:'@travetto/overview', folder:'@travetto/overview', displayName: 'Overview Docs',

package/src/mod.ts

@@ -1,6 +1,8 @@
+import { TypedObject } from '@travetto/base';
+
 import { node } from './nodes';
 import { MOD_MAPPING } from './mod-mapping';
 
-export const mod = Object.fromEntries(
-  Object.entries(MOD_MAPPING).map(([k, v]) => [k, node.Mod(v.name, v)])
+export const mod = TypedObject.fromEntries(
+  TypedObject.entries(MOD_MAPPING).map(([k, v]) => [k, node.Mod(v.name, v)])
 );

package/src/nodes.ts

@@ -107,6 +107,11 @@ export const node = {
    * @param content
    */
   SubSection: (title: Content) => $n('subsection', { title: $c(title) }),
+  /**
+   * Sub-sub-section
+   * @param content
+   */
+  SubSubSection: (title: Content) => $n('subsubsection', { title: $c(title) }),
   /**
    * Library reference
    * @param content
@@ -209,11 +214,14 @@ export const node = {
    * @param outline
    * @param language
    */
-  Code: (title: Content, content: Content | Function, outline = false, language = 'typescript') => {
+  Code: (title: Content, content: Content | Function, outline = false, language = 'typescript', rewrite?: (text: string) => string) => {
     if (typeof content === 'function') {
       content = RootIndex.getFunctionMetadata(content)!.source;
     }
     const res = ResolveUtil.resolveCode(content, language, outline);
+    if (rewrite && typeof res.content === 'string') {
+      res.content = rewrite(res.content);
+    }
     return $n('code', { title: $c(title), content: $c(res.content), language: res.language, file: $c(res.file) });
   },
 
@@ -268,13 +276,18 @@ export const node = {
   },
 
   /**
-   * NPM Installation
+   * Installing a package or program
    * @param title
    * @param pkg
    */
   Install: (title: Content, pkg: Content) => {
-    pkg = typeof pkg === 'string' && !pkg.includes(' ') ? `npm install ${pkg}` : pkg;
-    return $n('install', { title: $c(title), language: 'bash', content: $c(pkg) });
+    if (typeof pkg === 'string' && !pkg.includes(' ')) {
+      return $n('install', {
+        title: $c(title), language: 'bash', content: $c(`npm install ${pkg}\n\n# or\n\nyarn add ${pkg}`)
+      });
+    } else {
+      return $n('install', { title: $c(title), language: 'bash', content: $c(pkg), subtype: undefined });
+    }
   },
 
   /**

package/src/render/html.ts

@@ -36,8 +36,9 @@ export const Html: Renderer = {
       case 'mod': return `<a class="module-link" href="${context.link(recurse(c.link), c)}" title="${recurse(c.description)}">${recurse(c.title)}</a>`;
       case 'image': return `<img src="${context.link(recurse(c.link), c)}" alt="${recurse(c.title)}">`;
       case 'section':
-      case 'subsection': {
-        const tag = c._type === 'section' ? 'h2' : 'h3';
+      case 'subsection':
+      case 'subsubsection': {
+        const tag = c._type === 'section' ? 'h2' : (c._type === 'subsection' ? 'h3' : 'h4');
         const title = recurse(c.title);
         return `<${tag} id="${context.getAnchorId(title)}">${title}</${tag}>`;
       }

package/src/render/markdown.ts

@@ -30,6 +30,7 @@ ${context.cleanText(recurse(c.content))}
       case 'image': return `![${recurse(c.title)}](${context.link(recurse(c.link), c)})`;
       case 'section': return `## ${recurse(c.title)}`;
       case 'subsection': return `### ${recurse(c.title)}`;
+      case 'subsubsection': return `#### ${recurse(c.title)}`;
       case 'command':
       case 'method':
       case 'path':

package/src/render/util.ts

@@ -15,10 +15,6 @@ export class RenderUtil {
 
   static #imported = new Map<string, { root: AllType, wrap?: Wrapper }>();
 
-  static purge(file: string): void {
-    this.#imported.delete(file);
-  }
-
   /**
    * Render content of file and format
    * @param file
@@ -31,7 +27,11 @@ export class RenderUtil {
       throw new Error(`Unknown renderer with format: ${fmt}`);
     }
 
-    const mod = RootIndex.getFromSource(file)?.import;
+    let mod = RootIndex.getFromSource(file)?.import;
+
+    if (RootIndex.manifest.moduleType === 'module') {
+      mod = `${mod}?ts=${Date.now()}`;
+    }
 
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     const res = await import(mod!) as DocumentShape;

package/src/types.ts

@@ -30,7 +30,7 @@ export interface RenderContextShape {
   baseUrl: string;
 
   /**
-   * Github root for travetto framework
+   * Github root for Travetto framework
    */
   travettoBaseUrl: string;
 

package/src/util/file.ts

@@ -105,8 +105,12 @@ export class FileUtil {
         if (info) {
           const [, space, __name, rest] = info;
           if (!rest.endsWith(';')) {
-            methodPrefix = space;
-            return x.replace(/[{]\s*$/, ';');
+            if (/\s*[{]\s*return.*$/.test(x)) {
+              return x.replace(/\s*[{]\s*return.*$/, ';');
+            } else {
+              methodPrefix = space;
+              return x.replace(/\s*[{]\s*$/, ';');
+            }
           }
         }
         return x;

package/src/util/resolve.ts

@@ -48,7 +48,7 @@ export class ResolveUtil {
   static resolveConfig<T>(content: string | T, language: string): { content: string | T, language: string, file?: string } {
     let file: string | undefined;
     if (typeof content === 'string') {
-      if (/^[@:A-Za-z0-9\/\\\-_.]+[.](ya?ml|properties)$/.test(content)) {
+      if (/^[@:A-Za-z0-9\/\\\-_.]+[.](json|ya?ml|properties)$/.test(content)) {
         const res = FileUtil.read(content);
         language = res.language;
         file = res.file;

package/src/util/run.ts

@@ -1,11 +1,14 @@
 import { spawnSync } from 'child_process';
 
-import { path } from '@travetto/manifest';
-import { Env, ExecUtil, ExecutionOptions, ExecutionState } from '@travetto/base';
+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;
+  rewrite?: (text: string) => string;
   module?: string;
   env?: Record<string, string>;
   profiles?: string[];
@@ -19,7 +22,7 @@ type RunState = {
 };
 
 class DocState {
-  baseline = new Date('2029-03-14T00:00:00.000').getTime();
+  baseline = COMMON_DATE;
   _s = 37;
   ids: Record<string, string> = {};
 
@@ -56,7 +59,7 @@ export class DocRunUtil {
         cwd: path.toPosix(config.cwd ?? path.cwd()),
         shell: '/bin/bash',
         env: {
-          ...Env.export(/^(TRV_.*|NODE_.*|.*COLOR.*|PATH)$/),
+          ...process.env,
           DEBUG: '0',
           TRV_MANIFEST: '',
           TRV_BUILD: 'warn',
@@ -73,15 +76,19 @@ export class DocRunUtil {
    */
   static cleanRunOutput(text: string, cfg: RunConfig): string {
     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(new RegExp(path.cwd(), 'g'), '.')
       .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;
   }
 

package/support/cli.doc.ts

@@ -1,7 +1,7 @@
 import fs from 'fs/promises';
 
 import { PackageUtil, path, RootIndex, watchFolders } from '@travetto/manifest';
-import { GlobalEnvConfig } from '@travetto/base';
+import { ExecUtil, GlobalEnvConfig } from '@travetto/base';
 import { CliCommand, OptionConfig, ListOptionConfig } from '@travetto/cli';
 
 import { RenderUtil } from '../src/render/util';
@@ -19,8 +19,9 @@ 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: 'DOC.ts' }),
+      input: this.option({ desc: 'Input File', def: input?.relativeFile ?? 'DOC.ts' }),
       outputs: this.listOption({ desc: 'Outputs', def: [] }),
       watch: this.boolOption({ desc: 'Watch' })
     };
@@ -52,32 +53,32 @@ export class DocCommand extends CliCommand<Options> {
 
     const outputs = this.cmd.outputs.map(output => output.includes('.') ? [path.extname(output).substring(1), path.resolve(output)] : [output, null] as const);
 
-    // If specifying output
-    const write = async (): Promise<void> => {
-      RenderUtil.purge(docFile);
+    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);
         }
       }
-    };
-
-    if (this.cmd.watch) {
-      await watchFolders([path.dirname(docFile)], write, {
-        filter: ev => ev.action === 'update' && ev.file === docFile
-      });
-    } else {
-      try {
-        await write();
-        console.log(`Wrote docs for ${this.cmd.input}`);
-      } catch (err) {
-        console.error(err);
-        this.exit(1);
-      }
+    } catch (err) {
+      console.error(err);
+      this.exit(1);
     }
   }
 }