@travetto/doc 7.1.2 → 7.1.4

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.2",
+  "version": "7.1.4",
   "description": "Documentation support for the Travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,12 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/runtime": "^7.1.2",
+    "@travetto/runtime": "^7.1.4",
     "@types/prismjs": "^1.26.5",
     "prismjs": "^1.30.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^7.1.2"
+    "@travetto/cli": "^7.1.4"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/jsx.ts

@@ -5,6 +5,7 @@ import type { MODULES } from './mapping/module.ts';
 import type { CodeProps, 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 } };
@@ -105,4 +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 }),
+  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/context.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { PackageUtil } from '@travetto/manifest';
 import { castTo, RuntimeIndex } from '@travetto/runtime';
 
-import { type JSXElementByFn, c } from '../jsx.ts';
+import { type JSXElementByFn, c, d } from '../jsx.ts';
 import { DocResolveUtil, type ResolvedCode, type ResolvedRef, type ResolvedSnippetLink } from '../util/resolve.ts';
 import { DocRunUtil } from '../util/run.ts';
 import { createElement, JSXRuntimeTag } from '../../support/jsx-runtime.ts';
@@ -56,7 +56,7 @@ export class RenderContext {
    * Get rebuilt comment
    */
   get rebuildStamp(): string {
-    return `Please modify ${this.file.replace(this.repoRoot, this.baseUrl)} and execute "npx trv doc" to rebuild`;
+    return `Please modify ${this.file.replace(this.repoRoot, this.baseUrl)} and execute "${d.trv} doc" to rebuild`;
   }
 
   /**

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,11 +53,7 @@ export const Html: RenderProvider<RenderContext> = {
   },
   Install: async ({ context, node }) => {
     const highlighted = highlight(`
-npm install ${node.props.pkg}
-
-# or
-
-yarn add ${node.props.pkg}
+${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,11 +56,7 @@ export const Markdown: RenderProvider<RenderContext> = {
   Install: async ({ context, node }) =>
     `\n\n**Install: ${node.props.title}**
 \`\`\`bash
-npm install ${node.props.pkg}
-
-# or
-
-yarn add ${node.props.pkg}
+${PackageDocUtil.getInstallInstructions(node.props.pkg, true)}
 \`\`\`
 `,
   Code: async ({ context, node, props }) => {

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/run.ts

@@ -1,6 +1,6 @@
 import os from 'node:os';
 import util from 'node:util';
-import { spawn, type ChildProcess } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import path from 'node:path';
 
 import { Env, ExecUtil, Runtime, RuntimeIndex } from '@travetto/runtime';
@@ -62,41 +62,37 @@ export class DocRunUtil {
       .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, value) => value);
-    if (config.filter) {
-      text = text.split(/\n/g).filter(config.filter).join('\n');
-    }
-    if (config.rewrite) {
-      text = config.rewrite(text);
+    if (config.filter || config.rewrite) {
+      text = text.split(/\n/g)
+        .filter(line => config.filter?.(line) ?? true)
+        .map(line => config.rewrite?.(line) ?? line)
+        .join('\n');
     }
     return text;
   }
 
-  /**
-   * Spawn command with appropriate environment, and cwd
-   */
-  static spawn(cmd: string, args: string[], config: RunConfig = {}): ChildProcess {
-    return spawn(cmd, args, {
-      cwd: config.workingDirectory ?? this.workingDirectory(config),
-      env: {
-        ...process.env,
-        ...Env.DEBUG.export(false),
-        ...Env.TRV_CLI_IPC.export(undefined),
-        ...Env.TRV_MANIFEST.export(''),
-        ...Env.TRV_BUILD.export('none'),
-        ...Env.TRV_ROLE.export(undefined),
-        ...Env.TRV_MODULE.export(config.module ?? ''),
-        ...config.env
-      }
-    });
-  }
-
   /**
    * Run command synchronously and return output
    */
   static async run(cmd: string, args: string[], config: RunConfig = {}): Promise<string> {
     let final: string;
     try {
-      const subProcess = this.spawn(cmd, args, config);
+      const spawnCmd = config.spawn ?? spawn;
+      const subProcess = spawnCmd(cmd, args, {
+        ...config,
+        cwd: config.workingDirectory ?? this.workingDirectory(config),
+        env: {
+          ...process.env,
+          ...Env.DEBUG.export(false),
+          ...Env.TRV_CLI_IPC.export(undefined),
+          ...Env.TRV_MANIFEST.export(''),
+          ...Env.TRV_BUILD.export('none'),
+          ...Env.TRV_ROLE.export(undefined),
+          ...Env.TRV_MODULE.export(config.module ?? ''),
+          ...config.env
+        }
+      });
+
       const result = await ExecUtil.getResult(subProcess, { catch: true });
       if (!result.valid) {
         throw new Error(result.stderr);

package/src/util/types.ts

@@ -1,9 +1,12 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+
 export type RunConfig = {
   filter?: (line: string) => boolean;
-  rewrite?: (text: string) => string;
+  rewrite?: (line: string) => string;
   module?: string;
   env?: Record<string, string>;
   workingDirectory?: string;
+  spawn?: (cmd: string, args: string[], options: SpawnOptions) => ChildProcess;
 };
 
 export type CodeProps = { title?: string, src: string | Function, language?: string, outline?: boolean, startRe?: RegExp, endRe?: RegExp };

package/support/cli.doc.ts

@@ -1,6 +1,5 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
 
 import { PackageUtil } from '@travetto/manifest';
 import { ExecUtil, Env, Runtime, WatchUtil } from '@travetto/runtime';
@@ -51,7 +50,7 @@ export class DocCommand implements CliCommandShape {
     const [first, ...args] = process.argv.slice(2).filter(arg => !/(-w|--watch)/.test(arg));
     await WatchUtil.watchCompilerEvents('change', async ({ file }) => {
       if (file === this.input) {
-        const subProcess = spawn(process.argv0, [Runtime.trvEntryPoint, first, ...args], {
+        const subProcess = ExecUtil.spawnPackageCommand('trv', [first, ...args], {
           cwd: Runtime.mainSourcePath,
           env: { ...process.env, ...Env.TRV_QUIET.export(true) },
           stdio: 'inherit'