@appium/docutils 2.2.2 → 2.3.1

package/lib/builder/site.ts

@@ -7,43 +7,62 @@
 
 import path from 'node:path';
 import type {TeenProcessExecOptions} from 'teen_process';
-import {exec} from 'teen_process';
 import {DEFAULT_SITE_DIR, NAME_BIN, NAME_MKDOCS, NAME_MKDOCS_YML} from '../constants';
 import {DocutilsError} from '../error';
 import {findMkDocsYml, isMkDocsInstalled, readMkDocsYml, requirePython} from '../fs';
 import {getLogger} from '../logger';
 import type {SpawnBackgroundProcessOpts} from '../util';
-import {relative, spawnBackgroundProcess, stopwatch} from '../util';
+import {execWithErrorHandling, relative, spawnBackgroundProcess, stopwatch} from '../util';
 
 const log = getLogger('mkdocs');
 
 /**
- * Runs `mkdocs serve`
- * @param pythonPath Path to Python 3 executable
- * @param args Extra args to `mkdocs build`
- * @param opts Extra options for `teen_process.Subprocess.start`
- * @param mkDocsPath Path to `mkdocs` executable
+ * Options for {@linkcode buildSite}.
  */
-async function doServe(
-  pythonPath: string,
-  args: string[] = [],
-  opts: SpawnBackgroundProcessOpts = {},
-) {
-  const finalArgs = ['-m', NAME_MKDOCS, 'serve', ...args];
-  log.debug('Executing %s via: %s, %O', NAME_MKDOCS, pythonPath, finalArgs);
-  return spawnBackgroundProcess(pythonPath, finalArgs, opts);
-}
+export interface BuildMkDocsOpts {
+  /**
+   * Path to `mkdocs.yml`
+   */
+  mkdocsYml?: string;
 
-/**
- * Runs `mkdocs build`
- * @param pythonPath Path to Python 3 executable
- * @param args Extra args to `mkdocs build`
- * @param opts Extra options to `teen_process.exec`
- */
-async function doBuild(pythonPath: string, args: string[] = [], opts: TeenProcessExecOptions = {}) {
-  const finalArgs = ['-m', NAME_MKDOCS, 'build', ...args];
-  log.debug('Executing %s via: %s, %O', NAME_MKDOCS, pythonPath, finalArgs);
-  return await exec(pythonPath, finalArgs, opts);
+  /**
+   * Path to output directory
+   */
+  siteDir?: string;
+
+  /**
+   * MkDocs theme to use
+   * @defaultValue 'mkdocs'
+   */
+  theme?: string;
+
+  /**
+   * Current working directory
+   * @defaultValue `process.cwd()`
+   */
+  cwd?: string;
+
+  /**
+   * Path to `package.json`
+   *
+   * Used to find `mkdocs.yml` if unspecified.
+   */
+  packageJson?: string;
+
+  /**
+   * If `true`, run `mkdocs serve` instead of `mkdocs build`
+   */
+  serve?: boolean;
+
+  /**
+   * Extra options for {@linkcode teen_process.exec}
+   */
+  execOpts?: TeenProcessExecOptions;
+
+  /**
+   * Extra options for {@linkcode spawnBackgroundProcess}
+   */
+  serveOpts?: SpawnBackgroundProcessOpts;
 }
 
 /**
@@ -107,50 +126,30 @@ export async function buildSite({
 }
 
 /**
- * Options for {@linkcode buildSite}.
+ * Runs `mkdocs serve`
+ * @param pythonPath Path to Python 3 executable
+ * @param args Extra args to `mkdocs build`
+ * @param opts Extra options for `teen_process.Subprocess.start`
+ * @param mkDocsPath Path to `mkdocs` executable
  */
-export interface BuildMkDocsOpts {
-  /**
-   * Path to `mkdocs.yml`
-   */
-  mkdocsYml?: string;
-
-  /**
-   * Path to output directory
-   */
-  siteDir?: string;
-
-  /**
-   * MkDocs theme to use
-   * @defaultValue 'mkdocs'
-   */
-  theme?: string;
-
-  /**
-   * Current working directory
-   * @defaultValue `process.cwd()`
-   */
-  cwd?: string;
-
-  /**
-   * Path to `package.json`
-   *
-   * Used to find `mkdocs.yml` if unspecified.
-   */
-  packageJson?: string;
-
-  /**
-   * If `true`, run `mkdocs serve` instead of `mkdocs build`
-   */
-  serve?: boolean;
-
-  /**
-   * Extra options for {@linkcode teen_process.exec}
-   */
-  execOpts?: TeenProcessExecOptions;
+async function doServe(
+  pythonPath: string,
+  args: string[] = [],
+  opts: SpawnBackgroundProcessOpts = {},
+) {
+  const finalArgs = ['-m', NAME_MKDOCS, 'serve', ...args];
+  log.debug('Executing %s via: %s, %O', NAME_MKDOCS, pythonPath, finalArgs);
+  return spawnBackgroundProcess(pythonPath, finalArgs, opts);
+}
 
-  /**
-   * Extra options for {@linkcode spawnBackgroundProcess}
-   */
-  serveOpts?: SpawnBackgroundProcessOpts;
+/**
+ * Runs `mkdocs build`
+ * @param pythonPath Path to Python 3 executable
+ * @param args Extra args to `mkdocs build`
+ * @param opts Extra options to `teen_process.exec`
+ */
+async function doBuild(pythonPath: string, args: string[] = [], opts: TeenProcessExecOptions = {}) {
+  const finalArgs = ['-m', NAME_MKDOCS, 'build', ...args];
+  log.debug('Executing %s via: %s, %O', NAME_MKDOCS, pythonPath, finalArgs);
+  return await execWithErrorHandling(pythonPath, finalArgs, opts);
 }

package/lib/cli/check.ts

@@ -10,19 +10,6 @@ import {getLogger} from '../logger';
 
 const log = getLogger('check');
 
-/**
- * Given a list of objects with `id` and `path` props, filters out the ones that do not exist
- * @param paths Filepaths
- * @returns Missing files
- */
-async function filterMissing(paths: MissingFileData[]): Promise<MissingFileData[]> {
-  const exists = await Promise.all(
-    paths.map(async ({id, path}) => ({id, path, exists: await fs.exists(path)}))
-  );
-  const results = _.reject(exists, 'exists');
-  return _.map(results, (result) => _.omit(result, 'exists'));
-}
-
 /**
  * Data structure describing a missing file; returned by {@linkcode filterMissing}
  */
@@ -88,3 +75,16 @@ export async function checkMissingPaths<T extends Record<string, Options>>(
 
   return true;
 }
+
+/**
+ * Given a list of objects with `id` and `path` props, filters out the ones that do not exist
+ * @param paths Filepaths
+ * @returns Missing files
+ */
+async function filterMissing(paths: MissingFileData[]): Promise<MissingFileData[]> {
+  const exists = await Promise.all(
+    paths.map(async ({id, path}) => ({id, path, exists: await fs.exists(path)}))
+  );
+  const results = _.reject(exists, 'exists');
+  return _.map(results, (result) => _.omit(result, 'exists'));
+}

package/lib/cli/index.ts

@@ -23,6 +23,10 @@ const pkg = readPackageSync({cwd: fs.findRoot(__dirname)});
 const log = getLogger('cli');
 const IMPLICATIONS_FAILED_REGEX = /implications\s+failed:\n\s*(.+)\s->\s(.+)$/i;
 
+/**
+ * Entry point for the docutils CLI.
+ * @param argv Raw argv values (without node/bin by default).
+ */
 export async function main(argv = hideBin(process.argv)) {
   const config = await findConfig(argv);
 

package/lib/fs.ts

@@ -140,6 +140,8 @@ export const readJson = _.memoize(
     JSON.parse(await fs.readFile(filepath, 'utf8')),
 );
 
+type WhichFunction = (cmd: string, opts?: {nothrow: boolean}) => Promise<string | null>;
+
 /**
  * Writes contents to a file. Any JSON objects are stringified
  * @param filepath - Path to file
@@ -152,8 +154,6 @@ export function writeFileString(filepath: string, content: JsonValue) {
   });
 }
 
-type WhichFunction = (cmd: string, opts?: {nothrow: boolean}) => Promise<string | null>;
-
 /**
  * `which` with memoization
  */

package/lib/init.ts

@@ -83,6 +83,60 @@ export const initMkDocs: ScaffoldTask<InitMkDocsOptions, MkDocsYml> = createScaf
   },
 );
 
+/**
+ * Options for {@linkcode initMkDocs}
+ */
+export interface InitMkDocsOptions extends ScaffoldTaskOptions {
+  copyright?: string;
+  repoName?: string;
+  repoUrl?: string;
+  siteDescription?: string;
+  siteName?: string;
+}
+
+export interface InitPythonOptions extends ScaffoldTaskOptions {
+  /**
+   * Path to `python` (v3.x) executable
+   */
+  pythonPath?: string;
+
+  /**
+   * If true, upgrade only
+   */
+  upgrade?: boolean;
+}
+
+/**
+ * Options for `init` command handler
+ *
+ * The props of the various "path" options are rewritten as `dest` for the scaffold tasks functions.
+ */
+export type InitOptions = Simplify<
+  Omit<InitPythonOptions & InitMkDocsOptions, 'dest'> & {
+    /**
+     * If `true` will install Python deps
+     */
+    python?: boolean;
+    /**
+     * If `true` will initialize a `mkdocs.yml` file
+     */
+    mkdocs?: boolean;
+    /**
+     * Path to existing `package.json` file
+     */
+    packageJson?: string;
+    /**
+     * Path to new or existing `mkdocs.yml` file
+     */
+    mkdocsYml?: string;
+
+    /**
+     * If `true`, upgrade only
+     */
+    upgrade?: boolean;
+  }
+>;
+
 /**
  * Installs Python dependencies
  * @param opts Options
@@ -127,17 +181,6 @@ export async function initPython({
   log.success('Successfully installed Python dependencies');
 }
 
-/**
- * Options for {@linkcode initMkDocs}
- */
-export interface InitMkDocsOptions extends ScaffoldTaskOptions {
-  copyright?: string;
-  repoName?: string;
-  repoUrl?: string;
-  siteDescription?: string;
-  siteName?: string;
-}
-
 /**
  * Main handler for `init` command.
  *
@@ -177,46 +220,3 @@ export async function init({
     });
   }
 }
-
-export interface InitPythonOptions extends ScaffoldTaskOptions {
-  /**
-   * Path to `python` (v3.x) executable
-   */
-  pythonPath?: string;
-
-  /**
-   * If true, upgrade only
-   */
-  upgrade?: boolean;
-}
-
-/**
- * Options for `init` command handler
- *
- * The props of the various "path" options are rewritten as `dest` for the scaffold tasks functions.
- */
-export type InitOptions = Simplify<
-  Omit<InitPythonOptions & InitMkDocsOptions, 'dest'> & {
-    /**
-     * If `true` will install Python deps
-     */
-    python?: boolean;
-    /**
-     * If `true` will initialize a `mkdocs.yml` file
-     */
-    mkdocs?: boolean;
-    /**
-     * Path to existing `package.json` file
-     */
-    packageJson?: string;
-    /**
-     * Path to new or existing `mkdocs.yml` file
-     */
-    mkdocsYml?: string;
-
-    /**
-     * If `true`, upgrade only
-     */
-    upgrade?: boolean;
-  }
->;

package/lib/logger.ts

@@ -47,6 +47,11 @@ rootLogger.pauseLogs();
  */
 const loggers: Map<string, WeakRef<typeof ConsolaInstance>> = new Map();
 
+/**
+ * Returns a tagged logger, creating and caching one if needed.
+ * @param tag Logger tag.
+ * @param parent Parent logger to derive from.
+ */
 export function getLogger(tag: string, parent = rootLogger) {
   if (loggers.has(tag)) {
     const logger = loggers.get(tag)?.deref();

package/lib/scaffold.ts

@@ -18,26 +18,6 @@ import {NAME_ERR_ENOENT} from './constants';
 const log = getLogger('init');
 const dryRunLog = getLogger('dry-run', log);
 
-/**
- * Creates a unified patch for display in "dry run" mode
- * @param filename - File name to use
- * @param oldData - Old data
- * @param newData - New Data
- * @returns Patch string
- */
-function makePatch<T extends JsonValue>(
-  filename: string,
-  oldData: T | string,
-  newData: T | string,
-  serializer: ScaffoldTaskSerializer<T> = stringifyJson
-) {
-  return createPatch(
-    filename,
-    _.isString(oldData) ? oldData : serializer(oldData),
-    _.isString(newData) ? newData : serializer(newData)
-  );
-}
-
 /**
  * Options for a task which are not the {@link ScaffoldTaskOptions base options}
  */
@@ -55,6 +35,84 @@ export type ScaffoldTask<Opts extends ScaffoldTaskOptions, T extends JsonObject>
   opts: Opts
 ) => Promise<ScaffoldTaskResult<T>>;
 
+/**
+ * Optional function which can be used to post-process the content of a file. Usually used to merge
+ * various options with existing content
+ */
+export type ScaffoldTaskTransformer<Opts extends ScaffoldTaskOptions, T extends JsonValue> = (
+  content: Readonly<T>,
+  opts: TaskSpecificOpts<Opts>,
+  pkg: Readonly<NormalizedPackageJson>
+) => T;
+
+/**
+ * A function which deserializes a string into a JS value.
+ */
+export type ScaffoldTaskDeserializer<T> = (content: string) => T;
+
+/**
+ * A function which serializes a JS value into a string.
+ */
+export type ScaffoldTaskSerializer<T> = (content: T) => string;
+
+/**
+ * Options for {@linkcode createScaffoldTask}
+ */
+export interface CreateScaffoldTaskOptions<Opts extends ScaffoldTaskOptions, T extends JsonValue> {
+  /**
+   * Transformer function
+   */
+  transform?: ScaffoldTaskTransformer<Opts, T>;
+  /**
+   * Deserializer function
+   */
+  deserialize?: ScaffoldTaskDeserializer<T>;
+  /**
+   * Serializer function
+   */
+  serialize?: ScaffoldTaskSerializer<T>;
+}
+
+/**
+ * Base options for all scaffold tasks
+ */
+export interface ScaffoldTaskOptions {
+  /**
+   * Current working directory
+   */
+  cwd?: string;
+  /**
+   * Destination file
+   */
+  dest?: string;
+  /**
+   * If `true` will not write files
+   */
+  dryRun?: boolean;
+  /**
+   * If `true` will overwrite fields in `typedoc.json`
+   */
+  overwrite?: boolean;
+  /**
+   * Path to `package.json`
+   */
+  packageJson?: string;
+}
+
+/**
+ * The return value of a {@linkcode ScaffoldTask}
+ */
+export interface ScaffoldTaskResult<T> {
+  /**
+   * The content of whatever it wrote or would write
+   */
+  content: T;
+  /**
+   * The filepath of whatever it wrote or would write
+   */
+  path: string;
+}
+
 /**
  * Factory for a {@linkcode ScaffoldTask}.
  *
@@ -153,79 +211,21 @@ export function createScaffoldTask<Opts extends ScaffoldTaskOptions, T extends J
 }
 
 /**
- * Optional function which can be used to post-process the content of a file. Usually used to merge
- * various options with existing content
- */
-export type ScaffoldTaskTransformer<Opts extends ScaffoldTaskOptions, T extends JsonValue> = (
-  content: Readonly<T>,
-  opts: TaskSpecificOpts<Opts>,
-  pkg: Readonly<NormalizedPackageJson>
-) => T;
-
-/**
- * A function which deserializes a string into a JS value.
- */
-export type ScaffoldTaskDeserializer<T> = (content: string) => T;
-
-/**
- * A function which serializes a JS value into a string.
- */
-export type ScaffoldTaskSerializer<T> = (content: T) => string;
-
-/**
- * Options for {@linkcode createScaffoldTask}
- */
-export interface CreateScaffoldTaskOptions<Opts extends ScaffoldTaskOptions, T extends JsonValue> {
-  /**
-   * Transformer function
-   */
-  transform?: ScaffoldTaskTransformer<Opts, T>;
-  /**
-   * Deserializer function
-   */
-  deserialize?: ScaffoldTaskDeserializer<T>;
-  /**
-   * Serializer function
-   */
-  serialize?: ScaffoldTaskSerializer<T>;
-}
-
-/**
- * Base options for all scaffold tasks
- */
-export interface ScaffoldTaskOptions {
-  /**
-   * Current working directory
-   */
-  cwd?: string;
-  /**
-   * Destination file
-   */
-  dest?: string;
-  /**
-   * If `true` will not write files
-   */
-  dryRun?: boolean;
-  /**
-   * If `true` will overwrite fields in `typedoc.json`
-   */
-  overwrite?: boolean;
-  /**
-   * Path to `package.json`
-   */
-  packageJson?: string;
-}
-
-/**
- * The return value of a {@linkcode ScaffoldTask}
+ * Creates a unified patch for display in "dry run" mode
+ * @param filename - File name to use
+ * @param oldData - Old data
+ * @param newData - New Data
+ * @returns Patch string
  */
-export interface ScaffoldTaskResult<T> {
-  /**
-   * The content of whatever it wrote or would write
-   */
-  content: T;
-  /**
-   * The filepath of whatever it wrote or would write
-   */
-  path: string;
+function makePatch<T extends JsonValue>(
+  filename: string,
+  oldData: T | string,
+  newData: T | string,
+  serializer: ScaffoldTaskSerializer<T> = stringifyJson
+) {
+  return createPatch(
+    filename,
+    _.isString(oldData) ? oldData : serializer(oldData),
+    _.isString(newData) ? newData : serializer(newData)
+  );
 }

package/lib/util.ts

@@ -7,6 +7,8 @@ import _ from 'lodash';
 import type {SpawnOptions} from 'node:child_process';
 import {spawn} from 'node:child_process';
 import path from 'node:path';
+import type {ExecError, TeenProcessExecOptions} from 'teen_process';
+import {exec} from 'teen_process';
 
 /**
  * Computes a relative path, prepending `./`
@@ -71,6 +73,8 @@ export const argify: (obj: Record<string, string | number | boolean | undefined>
     _.flatten
   );
 
+export type SpawnBackgroundProcessOpts = Omit<SpawnOptions, 'stdio'>;
+
 /**
  * Spawns a long-running "background" child process.  This is expected to only return control to the
  * parent process in the case of a nonzero exit code from the child process.
@@ -95,4 +99,19 @@ export async function spawnBackgroundProcess(command: string, args: string[], op
   });
 }
 
-export type SpawnBackgroundProcessOpts = Omit<SpawnOptions, 'stdio'>;
+/**
+ * Wraps {@linkcode exec} with error handling that appends stderr to the thrown error message.
+ */
+export async function execWithErrorHandling(
+  cmd: string,
+  args?: string[],
+  opts?: TeenProcessExecOptions,
+) {
+  try {
+    return await exec(cmd, args, opts);
+  } catch (err) {
+    const execErr = err as ExecError;
+    execErr.message = execErr.stderr ? `${execErr.message}\nCommand error:\n${execErr.stderr}` : execErr.message;
+    throw execErr;
+  }
+}