@travetto/doc 7.1.3 → 8.0.0-alpha.0

package/__index__.ts

@@ -2,4 +2,5 @@ export { type JSXElement as DocJSXElement, isJSXElement as isDocJSXElement } fro
 export { c, d, JSXElementByFn as DocJSXElementByFn } from './src/jsx.ts';
 export { MODULES as module } from './src/mapping/module.ts';
 export { DocFileUtil } from './src/util/file.ts';
-export { DocRunUtil, COMMON_DATE } from './src/util/run.ts';
+export { DocRunUtil, COMMON_DATE } from './src/util/run.ts';
+export { PackageDocUtil } from './src/util/package.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/doc",
-  "version": "7.1.3",
+  "version": "8.0.0-alpha.0",
   "description": "Documentation support for the Travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,12 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/runtime": "^7.1.3",
-    "@types/prismjs": "^1.26.5",
+    "@travetto/runtime": "^8.0.0-alpha.0",
+    "@types/prismjs": "^1.26.6",
     "prismjs": "^1.30.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^7.1.3"
+    "@travetto/cli": "^8.0.0-alpha.0"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/jsx.ts

@@ -1,11 +1,11 @@
-import { castTo, Runtime, TypedObject } from '@travetto/runtime';
-import { PackageUtil } from '@travetto/manifest';
+import { castTo, TypedObject } from '@travetto/runtime';
 
 import type { LIBRARIES } from './mapping/library.ts';
 import type { MODULES } from './mapping/module.ts';
-import type { CodeProps, RunConfig } from './util/types.ts';
+import type { CodeProps, CodeSourceInput, RunConfig } from './util/types.ts';
 
 import { createElement, type JSXElement, type JSXComponentFunction as CompFn } from '../support/jsx-runtime.ts';
+import { PackageDocUtil } from './util/package.ts';
 
 type InstallProps = { title: string, pkg: string };
 type ExecProps = { title: string, cmd: string, args?: string[], config?: RunConfig & { formatCommand?(cmd: string, args: string[]): string } };
@@ -14,7 +14,7 @@ type HeaderProps = { title: string, description?: string };
 type ModuleProps = { name: keyof typeof MODULES };
 type LibraryProps = { name: keyof typeof LIBRARIES };
 type LinkProps = { title: string, href: string, line?: number };
-type CodeLinkProps = { title: string, src: string | Function, startRe: RegExp };
+type CodeLinkProps = { title: string, src: CodeSourceInput, startRe: RegExp };
 type Named = { name: string };
 type Titled = { title: string };
 
@@ -83,7 +83,7 @@ function CodeLinker(titleOrNode: string | JSXElement, src?: string, startRe?: Re
     props = { title: titleOrNode, src: src!, startRe: startRe! };
   } else if (titleOrNode.type === Code) {
     const node: JSXElementByFn<'Code'> = castTo(titleOrNode);
-    const srcName = typeof node.props.src === 'string' ? node.props.src : node.props.src.name;
+    const srcName = typeof node.props.src === 'string' ? node.props.src : (typeof node.props.src === 'function' ? node.props.src.name : '<UNNAMED>');
     props = {
       title: node.props.title ?? srcName,
       src: node.props.src,
@@ -106,7 +106,5 @@ export const d = {
   field: (name: string) => createElement(c.Field, { name }),
   library: (name: keyof typeof LIBRARIES) => createElement(c.Library, { name }),
   module: (name: keyof typeof MODULES) => createElement(c.Module, { name }),
-  installCommand: (pkg: string, production?: boolean) => PackageUtil.getInstallCommand(Runtime, pkg, production),
-  workspaceInitCommand: () => PackageUtil.getWorkspaceInitCommand(Runtime),
-  get trv() { return PackageUtil.getPackageCommand(Runtime, 'trv'); },
+  get trv() { return PackageDocUtil.getPackageCommand('trv'); },
 };

package/src/mapping/library.ts

@@ -5,7 +5,8 @@ export const LIBRARIES = {
   Node: { title: 'Node', href: 'https://nodejs.org' },
   TravettoPlugin: { title: 'VSCode plugin', href: 'https://marketplace.visualstudio.com/items?itemName=arcsine.travetto-plugin' },
   Npm: { title: 'Npm', href: 'https://docs.npmjs.com/downloading-and-installing-node-js-and-npm' },
-  Yarn: { title: 'Yarn', href: 'https://yarnpg.com' },
+  Yarn: { title: 'Yarn', href: 'https://yarnpkg.com' },
+  Pnpm: { title: 'Pnpm', href: 'https://pnpm.io/' },
   Eslint: { title: 'ESLint', href: 'https://eslint.org/' },
   Rollup: { title: 'Rollup', href: 'https://rollupjs.org/' },
   TSConfig: { title: 'TS Config', href: 'https://www.typescriptlang.org/docs/handbook/tsconfig-json.html' },

package/src/render/html.ts

@@ -11,6 +11,7 @@ import { LIBRARIES } from '../mapping/library.ts';
 import type { RenderContext } from './context.ts';
 import { DocResolveUtil } from '../util/resolve.ts';
 import type { JSXElement } from '../../support/jsx-runtime.ts';
+import { PackageDocUtil } from '../util/package.ts';
 
 const ESCAPE_ENTITIES: Record<string, string> = { '<': '&lt;', '>': '&gt;', '&': '&amp;', '{': "{{'{'}}", '}': "{{'}'}}" };
 const ENTITY_REGEX = new RegExp(`[${Object.keys(ESCAPE_ENTITIES).join('')}]`, 'gm');
@@ -52,7 +53,7 @@ export const Html: RenderProvider<RenderContext> = {
   },
   Install: async ({ context, node }) => {
     const highlighted = highlight(`
-${PackageUtil.getInstallInstructions(node.props.pkg, true)}
+${PackageDocUtil.getInstallInstructions(node.props.pkg, true)}
 `, 'bash');
 
     return `\n

package/src/render/markdown.ts

@@ -9,6 +9,7 @@ import { MODULES } from '../mapping/module.ts';
 import { LIBRARIES } from '../mapping/library.ts';
 import type { RenderContext } from './context.ts';
 import { DocResolveUtil } from '../util/resolve.ts';
+import { PackageDocUtil } from '../util/package.ts';
 
 export const Markdown: RenderProvider<RenderContext> = {
   ext: 'md',
@@ -55,7 +56,7 @@ export const Markdown: RenderProvider<RenderContext> = {
   Install: async ({ context, node }) =>
     `\n\n**Install: ${node.props.title}**
 \`\`\`bash
-${PackageUtil.getInstallInstructions(node.props.pkg, true)}
+${PackageDocUtil.getInstallInstructions(node.props.pkg, true)}
 \`\`\`
 `,
   Code: async ({ context, node, props }) => {

package/src/render/renderer.ts

@@ -45,10 +45,10 @@ export class DocRenderer {
   ) {
     const source = DocFileUtil.readSource(cls);
     if (source) {
-      title = (await DocFileUtil.isDecorator(cls.name, source.file)) ? `@${title ?? cls.name}` : (title ?? cls.name);
+      title = DocFileUtil.isDecorator(cls.name, source.file) ? `@${title ?? cls.name}` : (title ?? cls.name);
       const node = this.#support.createElement('CodeLink', {
         src: source.file,
-        startRe: new RegExp(`(class|function|interface)\\s+(${cls.name.replaceAll('$', '\\$')})`),
+        startRe: new RegExp(`(class|function|interface)\\s+(${RegExp.escape(cls.name)})`),
         title
       });
       // @ts-expect-error

package/src/util/file.ts

@@ -1,9 +1,11 @@
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 
-import { AppError, Runtime, RuntimeIndex } from '@travetto/runtime';
+import { RuntimeError, Runtime, RuntimeIndex } from '@travetto/runtime';
 import { type ManifestModuleFileType, ManifestModuleUtil } from '@travetto/manifest';
 
+import type { CodeSourceInput } from './types.ts';
+
 const ESLINT_PATTERN = /\s{0,10}\/\/ eslint.{0,300}$/g;
 const ENV_KEY = /Env.([^.]{1,100})[.]key/g;
 
@@ -24,6 +26,9 @@ const EXT_TO_LANG: Record<string, string> = {
   '.sh': 'bash',
 };
 
+type SourceOutput = { content: string, language: string, file: string };
+type SnippetOutput = { file: string, startIdx: number, lines: string[], language: string };
+
 /**
  * Standard file utilities
  */
@@ -35,7 +40,7 @@ export class DocFileUtil {
     return /^[@:A-Za-z0-9\/\\\-_.]+[.]([a-z]{2,10})$/.test(file);
   }
 
-  static readSource(input: string | Function): { content: string, language: string, file: string } {
+  static readSource(input: Exclude<CodeSourceInput, Promise<string>>): SourceOutput {
     let file: string | undefined;
     let content: string | undefined;
 
@@ -55,7 +60,7 @@ export class DocFileUtil {
     } else {
       file = Runtime.getSourceFile(input);
       if (!existsSync(file)) {
-        throw new AppError(`Unknown file: ${typeof input === 'string' ? input : input.name} => ${file}`);
+        throw new RuntimeError(`Unknown file: ${typeof input === 'string' ? input : input.name} => ${file}`);
       }
       content = readFileSync(file, 'utf8');
     }
@@ -83,8 +88,8 @@ export class DocFileUtil {
     }
   }
 
-  static async readCodeSnippet(input: string | Function, startPattern: RegExp): Promise<{ file: string, startIdx: number, lines: string[], language: string }> {
-    const result = this.readSource(input);
+  static async readCodeSnippet(input: CodeSourceInput, startPattern: RegExp): Promise<SnippetOutput> {
+    const result = this.readSource(await input);
     const lines = result.content.split(/\n/);
     const startIdx = lines.findIndex(line => startPattern.test(line));
     if (startIdx < 0) {
@@ -96,14 +101,14 @@ export class DocFileUtil {
   /**
    * Determine if a file is a decorator
    */
-  static async isDecorator(name: string, file: string): Promise<boolean> {
+  static isDecorator(name: string, file: string): boolean {
 
     const key = `${name}:${file}`;
     if (key in this.#decCache) {
       return this.#decCache[key];
     }
 
-    const text = await this.readSource(file);
+    const text = this.readSource(file);
     const lines = text.content.split(/\n/g);
 
     const start = lines.findIndex(line => new RegExp(`function ${name}\\b`).test(line));

package/src/util/package.ts

@@ -0,0 +1,46 @@
+import { PACKAGE_MANAGERS, type NodePackageManager } from '@travetto/manifest';
+import { Runtime } from '@travetto/runtime';
+
+export class PackageDocUtil {
+  /**
+   * Get an the command for executing a package level binary
+   */
+  static getPackageCommand(pkg: string, args: string[] = [], manager?: NodePackageManager): string {
+    switch (manager ?? Runtime.workspace.manager) {
+      case 'npm':
+      case 'yarn': return `npx ${pkg} ${args.join(' ')}`.trim();
+      case 'pnpm': return `pnpm ${pkg} ${args.join(' ')}`.trim();
+    }
+  }
+
+  /**
+   * Get an the command for executing a package level binary
+   */
+  static getWorkspaceInitCommand(manager?: NodePackageManager): string {
+    switch (manager ?? Runtime.workspace.manager) {
+      case 'npm': return 'npm init -f';
+      case 'yarn': return 'yarn init -y';
+      case 'pnpm': return 'pnpm init -y';
+    }
+  }
+
+  /**
+   * Get an install command for a given npm module
+   */
+  static getInstallCommand(pkg: string, production = false, manager?: NodePackageManager): string {
+    switch (manager ?? Runtime.workspace.manager) {
+      case 'npm': return `npm install ${production ? '' : '--save-dev '}${pkg}`;
+      case 'yarn': return `yarn add ${production ? '' : '--dev '}${pkg}`;
+      case 'pnpm': return `pnpm add ${production ? '' : '--dev '}${pkg}`;
+    }
+  }
+
+  /**
+   * Get install example for a given package
+   */
+  static getInstallInstructions(pkg: string, production = false): string {
+    return PACKAGE_MANAGERS
+      .map(manager => this.getInstallCommand(pkg, production, manager.type))
+      .join('\n\n# or\n\n');
+  }
+}

package/src/util/resolve.ts

@@ -1,5 +1,5 @@
 import { DocFileUtil } from './file.ts';
-import type { CodeProps } from './types.ts';
+import type { CodeProps, CodeSourceInput } from './types.ts';
 
 export type ResolvedRef = { title: string, file: string, line: number };
 export type ResolvedCode = { text: string, language: string, file?: string };
@@ -14,26 +14,26 @@ export class DocResolveUtil {
   static async resolveRef(title: string, file: string): Promise<ResolvedRef> {
 
     let line = 0;
-    const result = await DocFileUtil.readSource(file);
+    const result = DocFileUtil.readSource(file);
     file = result.file;
 
     if (result.content) {
       line = result.content.split(/\n/g)
-        .findIndex(lineText => new RegExp(`(class|interface|function)[ ]+${title.replaceAll('$', '\\$')}`).test(lineText));
+        .findIndex(lineText => new RegExp(`(class|interface|function)[ ]+${RegExp.escape(title)}`).test(lineText));
       if (line < 0) {
         line = 0;
       } else {
         line += 1;
       }
-      if (await DocFileUtil.isDecorator(title, file)) {
+      if (DocFileUtil.isDecorator(title, file)) {
         title = `@${title}`;
       }
     }
     return { title, file, line };
   }
 
-  static async resolveCode(content: string | Function, language?: string, outline = false): Promise<ResolvedCode> {
-    const result = DocFileUtil.readSource(content);
+  static async resolveCode(content: CodeSourceInput, language?: string, outline = false): Promise<ResolvedCode> {
+    const result = DocFileUtil.readSource(await content);
     let text = result.content;
 
     let file: string | undefined;
@@ -47,7 +47,7 @@ export class DocResolveUtil {
     return { text, language: language!, file };
   }
 
-  static async resolveSnippet(file: Function | string, startPattern: RegExp, endPattern?: RegExp, outline = false): Promise<ResolvedSnippet> {
+  static async resolveSnippet(file: CodeSourceInput, startPattern: RegExp, endPattern?: RegExp, outline = false): Promise<ResolvedSnippet> {
     const { lines, startIdx, language, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
 
     const endIdx = endPattern ? lines.findIndex((line, i) => i > startIdx && endPattern.test(line)) : lines.length;
@@ -60,14 +60,14 @@ export class DocResolveUtil {
     return { text, language, line: startIdx + 1, file: resolvedFile };
   }
 
-  static async resolveCodeLink(file: Function | string, startPattern: RegExp): Promise<ResolvedSnippetLink> {
+  static async resolveCodeLink(file: CodeSourceInput, startPattern: RegExp): Promise<ResolvedSnippetLink> {
     const { startIdx, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
     return { file: resolvedFile, line: startIdx + 1 };
   }
 
-  static applyCodePropDefaults(props: CodeProps) {
+  static applyCodePropDefaults(props: CodeProps): void {
     const type = typeof props.src === 'function' ? props.src : undefined;
-    props.startRe ??= (type ? new RegExp(`^(export)?\\s*(interface|class)\\s+${type.name.replaceAll('$', '\\$')}\\b`) : undefined);
+    props.startRe ??= (type ? new RegExp(`^(export)?\\s*(interface|class)\\s+${RegExp.escape(type.name)}\\b`) : undefined);
     props.language ??= (type ? 'typescript' : undefined);
     props.endRe ??= (type ? /^[}]/ : undefined);
     props.title ??= typeof props.src == 'function' ? props.src.name.replace(/^[$]/, '') : undefined;

package/src/util/run.ts

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { Env, ExecUtil, Runtime, RuntimeIndex } from '@travetto/runtime';
 import type { RunConfig } from './types.ts';
 
-export const COMMON_DATE = new Date('2029-03-14T00:00:00.000').getTime();
+export const COMMON_DATE = new Date('2029-03-14T00:00:00.000-0400').getTime();
 
 class DocState {
   baseline = COMMON_DATE;

package/src/util/types.ts

@@ -9,4 +9,6 @@ export type RunConfig = {
   spawn?: (cmd: string, args: string[], options: SpawnOptions) => ChildProcess;
 };
 
-export type CodeProps = { title?: string, src: string | Function, language?: string, outline?: boolean, startRe?: RegExp, endRe?: RegExp };
+export type CodeSourceInput = string | Promise<string> | Function;
+
+export type CodeProps = { title?: string, src: CodeSourceInput, language?: string, outline?: boolean, startRe?: RegExp, endRe?: RegExp };