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

package/src/nodes.ts

@@ -1,5 +1,6 @@
-import { PathUtil, Package, FsUtil } from '@travetto/boot';
-import { readPackage } from '@travetto/boot/src/internal/package';
+import { existsSync } from 'fs';
+
+import { path, RootIndex, PackageUtil } from '@travetto/manifest';
 
 import { FileUtil, } from './util/file';
 import { DocRunUtil, RunConfig } from './util/run';
@@ -18,6 +19,8 @@ const $n = <T extends string, U extends Record<string, unknown>>(t: T, values: U
   // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
   ({ _type: t, ...values } as { _type: T } & U);
 
+type FormattedCommand = { formatCommand?(cmd: string, args: string[]): string };
+
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
 
 /**
@@ -104,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
@@ -156,27 +164,34 @@ export const node = {
    * @param args
    * @param cfg
    */
-  Execute: (title: Content, cmd: string, args: string[] = [], cfg: RunConfig = {}) => {
+  Execute: (title: Content, cmd: string, args: string[] = [], cfg: RunConfig & FormattedCommand = {}) => {
     if (cmd !== 'trv') {
-      cmd = FileUtil.resolveFile(cmd).resolved.replace(PathUtil.cwd, '.');
+      cmd = FileUtil.resolveFile(cmd).replace(path.cwd(), '.');
     }
 
     const script = DocRunUtil.run(cmd, args, cfg);
-    const prefix = !/.*\/doc\/.*[.]ts$/.test(cmd) ? '$' :
-      `$ node @travetto/${cfg.module ?? 'base'}/bin/main`;
+    const prefix = !/.*\/doc\/.*[.]ts$/.test(cmd) ? '$' : '$ node ';
+
+    const commandDisplay = cfg.formatCommand?.(cmd, args) ?? `${cmd} ${args.join(' ')}`;
 
-    return node.Terminal(title, `${prefix} ${cmd} ${args.join(' ')}\n\n${script}`);
+    return node.Terminal(title, `${prefix} ${commandDisplay}\n\n${script}`);
   },
 
   /**
    * Node Module Reference
-   * @param folder
-   */
-  Mod(folder: string) {
-    folder = PathUtil.resolveFrameworkPath(PathUtil.resolveUnix('node_modules', folder));
-
-    const { description, displayName } = readPackage(folder);
-    return $n('mod', { title: $c(displayName!), link: $c(folder), description: $c(description!) });
+   * @param name
+   */
+  Mod(name: string, cfg?: { folder: string, displayName: string, description: string }) {
+    if (!cfg) {
+      const folder = RootIndex.getModule(name)!.sourcePath;
+      const pkg = PackageUtil.readPackage(folder);
+      cfg = {
+        folder,
+        displayName: pkg.travetto!.displayName!,
+        description: pkg.description!
+      };
+    }
+    return $n('mod', { title: $c(cfg.displayName), link: $c(cfg.folder), description: $c(cfg.description), name: $c(name) });
   },
 
   /**
@@ -184,7 +199,10 @@ export const node = {
    * @param title
    * @param file
    */
-  Ref: (title: Content, file: string) => {
+  Ref: (title: Content, file: string | Function) => {
+    if (typeof file === 'function') {
+      file = RootIndex.getFunctionMetadata(file)!.source;
+    }
     const res = ResolveUtil.resolveRef(title, file);
     return $n('ref', { title: $c(res.title), link: $c(res.file), line: res.line });
   },
@@ -196,8 +214,14 @@ export const node = {
    * @param outline
    * @param language
    */
-  Code: (title: Content, content: Content, 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) });
   },
 
@@ -217,8 +241,13 @@ export const node = {
    * @param install
    * @param pkg
    */
-  Header: (install = true, pkg = Package) =>
-    $n('header', { title: $c(pkg.displayName ?? pkg.name), description: $c(pkg.description), package: pkg.name, install }),
+  Header: (mod?: string, install = true) => {
+    if (!mod) {
+      mod = RootIndex.mainPackage.name;
+    }
+    const pkg = PackageUtil.readPackage(RootIndex.getModule(mod)!.sourcePath);
+    return $n('header', { title: $c(pkg.travetto?.displayName ?? pkg.name), description: $c(pkg.description), package: pkg.name, install });
+  },
 
   /**
    * Comment
@@ -235,7 +264,10 @@ export const node = {
    * @param endPattern
    * @param outline
    */
-  Snippet: (title: Content, file: string, startPattern: RegExp, endPattern?: RegExp, outline?: boolean) => {
+  Snippet: (title: Content, file: string | Function, startPattern: RegExp, endPattern?: RegExp, outline?: boolean) => {
+    if (typeof file !== 'string') {
+      file = RootIndex.getFunctionMetadata(file)!.source;
+    }
     const res = ResolveUtil.resolveSnippet(file, startPattern, endPattern, outline);
     return $n('code', {
       title: $c(title), content: $c(res.text), line: res.line, file: $c(res.file), language: res.language,
@@ -244,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 });
+    }
   },
 
   /**
@@ -284,7 +321,7 @@ export const node = {
    * @param file
    */
   Image: (title: Content, file: string) => {
-    if (!/^https?:/.test(file) && !FsUtil.existsSync(file)) {
+    if (!/^https?:/.test(file) && !existsSync(file)) {
       throw new Error(`${file} is not a valid location`);
     }
     return $n('image', { title: $c(title), link: $c(file) });

package/src/render/code-highlight.ts

@@ -1,31 +1,24 @@
-type Lang = {};
-
-// TODO: Get proper typings
-const Prism: {
-  plugins: { NormalizeWhitespace: Record<string, Function> };
-  languages: Record<string, Lang>;
-  highlight(text: string, grammar: Lang, language: string): string;
-} = require('prismjs');
-
-import 'prismjs/plugins/normalize-whitespace/prism-normalize-whitespace';
-import 'prismjs/components/prism-typescript';
-import 'prismjs/components/prism-javascript';
-import 'prismjs/components/prism-css';
-import 'prismjs/components/prism-scss';
-import 'prismjs/components/prism-yaml';
-import 'prismjs/components/prism-json';
-import 'prismjs/components/prism-sql';
-import 'prismjs/components/prism-properties';
-import 'prismjs/components/prism-bash';
-
-Prism.plugins.NormalizeWhitespace.setDefaults({
+import { default as prismjs } from 'prismjs';
+
+import 'prismjs/plugins/normalize-whitespace/prism-normalize-whitespace.js';
+import 'prismjs/components/prism-typescript.js';
+import 'prismjs/components/prism-javascript.js';
+import 'prismjs/components/prism-css.js';
+import 'prismjs/components/prism-scss.js';
+import 'prismjs/components/prism-yaml.js';
+import 'prismjs/components/prism-json.js';
+import 'prismjs/components/prism-sql.js';
+import 'prismjs/components/prism-properties.js';
+import 'prismjs/components/prism-bash.js';
+
+prismjs.plugins.NormalizeWhitespace.setDefaults({
   'remove-trailing': true,
   'remove-indent': true,
   'left-trim': true,
   'right-trim': true
 });
 
-const nw = Prism.plugins.NormalizeWhitespace;
+const nw = prismjs.plugins.NormalizeWhitespace;
 
 const tokenMapping: { [key: string]: string } = {
   gt: '>',
@@ -44,7 +37,7 @@ export function highlight(text: string, lang: string): string | undefined {
     .replace(/&([a-z][^;]*);/g, (a, k) => tokenMapping[k] || a);
 
   try {
-    return Prism.highlight(text, Prism.languages[lang], lang)
+    return prismjs.highlight(text, prismjs.languages[lang], lang)
       .replace(/(@\s*<span[^>]*)function("\s*>)/g, (a, pre, post) => `${pre}meta${post}`)
       .replace(/[{}]/g, a => `{{'${a}'}}`);
   } catch (err) {

package/src/render/context.ts

@@ -1,6 +1,4 @@
-import * as path from 'path';
-
-import { PathUtil, FsUtil, Package, EnvUtil } from '@travetto/boot';
+import { path } from '@travetto/manifest';
 
 import { AllType, AllTypeMap, node as n } from '../nodes';
 import { DocNode, RenderContextShape } from '../types';
@@ -13,31 +11,15 @@ export type AllChildren = AllType;
 export class RenderContext implements RenderContextShape {
 
   file: string;
+  baseUrl: string;
+  travettoBaseUrl: string;
+  repoRoot: string;
 
-  constructor(file: string) {
-    this.file = PathUtil.resolveUnix(file);
-  }
-
-  get #repoUrl(): string {
-    return (Package.repository?.url ?? '').replace(/[.]git$/, '');
-  }
-
-  get gitBaseUrl(): string {
-    return `${this.#repoUrl}/tree/${EnvUtil.get('TRV_DOC_BRANCH', 'main')}`;
-  }
-
-  get travettoGitBaseUrl(): string {
-    return this.#repoUrl.includes('travetto/travetto') ? this.gitBaseUrl : 'https://github.com/travetto/travetto/main';
-  }
-
-  get gitFolder(): string {
-    let base = PathUtil.cwd;
-
-    while (base && !(FsUtil.existsSync(PathUtil.resolveUnix(base, '.git')))) {
-      base = path.dirname(base);
-    }
-
-    return `${this.gitBaseUrl}${PathUtil.cwd.replace(base, '')}`;
+  constructor(file: string, repoRoot: string, baseUrl: string, travettoBaseUrl: string) {
+    this.file = path.toPosix(file);
+    this.baseUrl = baseUrl;
+    this.repoRoot = repoRoot;
+    this.travettoBaseUrl = travettoBaseUrl;
   }
 
   toc(root: DocNode): AllTypeMap['Ordered'] {
@@ -57,15 +39,14 @@ export class RenderContext implements RenderContextShape {
     return n.Group([
       n.Comment('This file was generated by @travetto/doc and should not be modified directly'),
       n.Text('\n'),
-      n.Comment(`Please modify ${this.file.replace(PathUtil.cwd, this.gitFolder)} and execute "npx trv doc" to rebuild`),
+      n.Comment(`Please modify ${this.file.replace(this.repoRoot, this.baseUrl)} and execute "npx trv doc" to rebuild`),
     ]);
   }
 
   link(text: string, line?: number | { [key: string]: unknown, line?: number }): string {
     const num = typeof line === 'number' ? line : line?.line;
-    text = PathUtil.normalizeFrameworkPath(text);
-    return `${text.replace(PathUtil.cwd, this.gitBaseUrl)
-      .replace(/.*@travetto\//, `${this.travettoGitBaseUrl}/module/`)}${num ? `#L${num}` : ''}`;
+    return `${text.replace(this.repoRoot, this.baseUrl)
+      .replace(/.*@travetto\//, `${this.travettoBaseUrl}/module/`)}${num ? `#L${num}` : ''}`;
   }
 
   cleanText(a?: string): string {

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':
@@ -60,7 +61,7 @@ ${context.cleanText(recurse(c.content))}
       case 'header':
         return `# ${recurse(c.title)}\n${c.description ? `## ${recurse(c.description)}\n` : ''}${'install' in c ? recurse(n.Install(c.package, c.package)) : ''}\n`;
       case 'text':
-        return c.content;
+        return c.content.replace(/ /g, ' ');
     }
   }
 };