@appium/docutils 0.2.2 → 0.3.1

package/lib/builder/site.ts

@@ -5,13 +5,14 @@
  * @module
  */
 
+import {spawn, SpawnOptions} from 'node:child_process';
 import path from 'node:path';
-import {exec, SubProcess, TeenProcessExecOptions} from 'teen_process';
-import {NAME_BIN, NAME_MKDOCS, NAME_MKDOCS_YML} from '../constants';
+import {exec, TeenProcessExecOptions} from 'teen_process';
+import {NAME_BIN, NAME_MKDOCS, NAME_MKDOCS_YML, NAME_THEME} from '../constants';
 import {DocutilsError} from '../error';
 import {findMkDocsYml, readMkDocsYml, whichMkDocs} from '../fs';
 import logger from '../logger';
-import {relative, stopwatch, TeenProcessSubprocessStartOpts} from '../util';
+import {relative, spawnBackgroundProcess, SpawnBackgroundProcessOpts, stopwatch} from '../util';
 
 const log = logger.withTag('mkdocs');
 
@@ -23,14 +24,14 @@ const log = logger.withTag('mkdocs');
  */
 async function doServe(
   args: string[] = [],
-  {startDetector, detach, timeoutMs}: TeenProcessSubprocessStartOpts = {},
+  opts: SpawnBackgroundProcessOpts = {},
   mkDocsPath?: string
 ) {
   mkDocsPath = mkDocsPath ?? (await whichMkDocs());
   const finalArgs = ['serve', ...args];
-  log.debug('Launching %s with args: %O', mkDocsPath, finalArgs);
-  const proc = new SubProcess(mkDocsPath, finalArgs);
-  return await proc.start(startDetector, detach, timeoutMs);
+
+  log.debug('Launching %s with args: %s', mkDocsPath, finalArgs);
+  return spawnBackgroundProcess(mkDocsPath, finalArgs, opts);
 }
 
 /**
@@ -57,7 +58,7 @@ async function doBuild(
 export async function buildSite({
   mkdocsYml: mkDocsYmlPath,
   siteDir,
-  theme = NAME_MKDOCS,
+  theme = NAME_THEME,
   cwd = process.cwd(),
   serve = false,
   serveOpts,
@@ -137,7 +138,7 @@ export interface BuildMkDocsOpts {
   execOpts?: TeenProcessExecOptions;
 
   /**
-   * Extra options for {@linkcode teen_process.Subprocess.start}
+   * Extra options for {@linkcode spawnBackgroundProcess}
    */
-  serveOpts?: TeenProcessSubprocessStartOpts;
+  serveOpts?: SpawnBackgroundProcessOpts;
 }

package/lib/cli/check.ts

@@ -0,0 +1,87 @@
+/**
+ * Provides functions to validate user-provided options as part of Yargs' post-parsing "check" phase
+ * @module
+ */
+
+import {fs, util} from '@appium/support';
+import _ from 'lodash';
+import type {Options} from 'yargs';
+import logger from '../logger';
+
+const log = logger.withTag('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}
+ */
+interface MissingFileData {
+  /**
+   * Arbitrary identifier; intent was to map to an option name
+   */
+  id: string;
+  /**
+   * Normalized filepath
+   */
+  path: string;
+}
+
+/**
+ * Takes user-provided paths and checks for existence.
+ *
+ * Filters options to consider based on group name only.
+ *
+ * Meant to be used as a "fail-fast" strategy on the CLI, so we don't go all the way through some
+ * expensive behavior before realizing we're missing a path.
+ * @param opts Options object for a yargs command
+ * @param group Group name to filter on
+ * @param argv User-provided args
+ * @returns `true` if all paths exist or otherwise an error message
+ */
+export async function checkMissingPaths<T extends Record<string, Options>>(
+  opts: T,
+  group: string,
+  argv: Record<string, unknown>
+): Promise<true | string> {
+  const argsToCheck = _.keys(
+    _.pickBy(opts, (opt: Options, id: string) => opt?.group === group && id in argv) as Partial<T>
+  );
+
+  // yargs is pretty loose about allowing CLI args multiple times, and the value could potentially
+  // be a `string[]` instead of `string`; we don't want to allow more than one path per arg.
+  if (!argsToCheck.every((id) => _.isString(argv[id]))) {
+    return 'Paths may only be provided once each';
+  }
+
+  const pathsToCheck: MissingFileData[] = _.map(argsToCheck, (id) => ({
+    id,
+    path: String(argv[id]), // this must be a string per the above check
+  }));
+
+  log.debug(
+    'Checking for existence of %s: %s',
+    util.pluralize('path', pathsToCheck.length),
+    _.map(pathsToCheck, 'path')
+  );
+
+  const missingPaths = await filterMissing(pathsToCheck);
+
+  if (missingPaths.length) {
+    return missingPaths
+      .map(({id, path}) => `Path specified using --${_.kebabCase(id)} (${path}) does not exist`)
+      .join('\n');
+  }
+
+  return true;
+}

package/lib/cli/command/build.ts

@@ -1,53 +1,64 @@
-import {CommandModule, InferredOptionTypes, Options} from 'yargs';
+/**
+ * Yargs command module for the `build` command.
+ * @module
+ */
+
+import path from 'node:path';
+import type {CommandModule, InferredOptionTypes, Options} from 'yargs';
 import {buildReferenceDocs, buildSite, deploy, updateNav} from '../../builder';
 import {NAME_BIN} from '../../constants';
 import logger from '../../logger';
 import {stopwatch} from '../../util';
+import {checkMissingPaths} from '../check';
 
 const log = logger.withTag('build');
 
-const NAME_GROUP_BUILD = 'Build Options:';
-const NAME_GROUP_DEPLOY = 'Deployment Options:';
-const NAME_GROUP_SERVE = 'Serve Options:';
-const NAME_GROUP_BUILD_PATHS = 'Paths:';
+enum BuildCommandGroup {
+  Build = 'Build Config:',
+  Deploy = 'Deployment Config:',
+  Serve = 'Dev Server Config:',
+  BuildPaths = 'Custom Paths:',
+}
 
-const opts = Object.freeze({
+const opts = {
   reference: {
     describe: 'Run TypeDoc command API reference build (Markdown)',
-    group: NAME_GROUP_BUILD,
+    group: BuildCommandGroup.Build,
     type: 'boolean',
     default: true,
   },
   site: {
     describe: 'Run MkDocs build (HTML)',
-    group: NAME_GROUP_BUILD,
+    group: BuildCommandGroup.Build,
     type: 'boolean',
     default: true,
   },
   'site-dir': {
     alias: 'd',
     describe: 'HTML output directory',
-    group: NAME_GROUP_BUILD_PATHS,
+    group: BuildCommandGroup.Build,
     nargs: 1,
     requiresArg: true,
     type: 'string',
     normalize: true,
+    coerce: path.resolve,
     implies: 'site',
     defaultDescription: '(from mkdocs.yml)',
   },
   'package-json': {
     defaultDescription: './package.json',
     describe: 'Path to package.json',
-    group: NAME_GROUP_BUILD_PATHS,
+    group: BuildCommandGroup.BuildPaths,
     nargs: 1,
     normalize: true,
+    coerce: path.resolve,
     requiresArg: true,
     type: 'string',
   },
   title: {
     defaultDescription: '(extension package name)',
     describe: 'Title of the API reference',
-    group: NAME_GROUP_BUILD,
+    group: BuildCommandGroup.Build,
     nargs: 1,
     requiresArg: true,
     type: 'string',
@@ -55,45 +66,48 @@ const opts = Object.freeze({
   'tsconfig-json': {
     defaultDescription: './tsconfig.json',
     describe: 'Path to tsconfig.json',
-    group: NAME_GROUP_BUILD_PATHS,
+    group: BuildCommandGroup.BuildPaths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
+    coerce: path.resolve,
     type: 'string',
   },
   'mkdocs-yml': {
     defaultDescription: './mkdocs.yml',
     description: 'Path to mkdocs.yml',
-    group: NAME_GROUP_BUILD_PATHS,
+    group: BuildCommandGroup.BuildPaths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
+    coerce: path.resolve,
     type: 'string',
   },
   'typedoc-json': {
     defaultDescription: './typedoc.json',
     describe: 'Path to typedoc.json',
-    group: NAME_GROUP_BUILD_PATHS,
+    group: BuildCommandGroup.BuildPaths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
+    coerce: path.resolve,
     type: 'string',
   },
   all: {
     describe: 'Output all reference docs (not just Appium comands)',
-    group: NAME_GROUP_BUILD,
+    group: BuildCommandGroup.Build,
     implies: 'site',
     type: 'boolean',
   },
   deploy: {
-    describe: 'Commit HTML output',
-    group: NAME_GROUP_DEPLOY,
+    describe: 'Commit HTML output to a branch using mike',
+    group: BuildCommandGroup.Deploy,
     type: 'boolean',
     implies: 'site',
   },
   push: {
     describe: 'Push after deploy',
-    group: NAME_GROUP_DEPLOY,
+    group: BuildCommandGroup.Deploy,
     type: 'boolean',
     implies: 'deploy',
   },
@@ -101,7 +115,7 @@ const opts = Object.freeze({
     alias: 'b',
     describe: 'Branch to commit to',
     implies: 'deploy',
-    group: NAME_GROUP_DEPLOY,
+    group: BuildCommandGroup.Deploy,
     type: 'string',
     requiresArg: true,
     nargs: 1,
@@ -111,7 +125,7 @@ const opts = Object.freeze({
     alias: 'r',
     describe: 'Remote to push to',
     implies: ['deploy', 'push'],
-    group: NAME_GROUP_DEPLOY,
+    group: BuildCommandGroup.Deploy,
     type: 'string',
     requiresArg: true,
     nargs: 1,
@@ -120,16 +134,16 @@ const opts = Object.freeze({
   prefix: {
     describe: 'Subdirectory within <branch> to commit to',
     implies: ['deploy', 'branch'],
-    group: NAME_GROUP_DEPLOY,
+    group: BuildCommandGroup.Deploy,
     type: 'string',
     nargs: 1,
     requiresArg: true,
   },
   message: {
     alias: 'm',
-    describe: 'Commit message',
+    describe: 'Commit message. Use "%s" for version placeholder',
     implies: 'deploy',
-    group: NAME_GROUP_DEPLOY,
+    group: BuildCommandGroup.Deploy,
     type: 'string',
     nargs: 1,
     requiresArg: true,
@@ -137,7 +151,7 @@ const opts = Object.freeze({
   'deploy-version': {
     describe: 'Version (directory) to deploy build to',
     implies: 'deploy',
-    group: NAME_GROUP_DEPLOY,
+    group: BuildCommandGroup.Deploy,
     type: 'string',
     nargs: 1,
     requiresArg: true,
@@ -146,7 +160,7 @@ const opts = Object.freeze({
   alias: {
     describe: 'Alias for the build (e.g., "latest"); triggers alias update',
     implies: 'deploy',
-    group: NAME_GROUP_DEPLOY,
+    group: BuildCommandGroup.Deploy,
     type: 'string',
     nargs: 1,
     requiresArg: true,
@@ -155,18 +169,18 @@ const opts = Object.freeze({
   rebase: {
     describe: 'Rebase <branch> with remote before deploy',
     implies: ['deploy', 'branch', 'remote'],
-    group: NAME_GROUP_DEPLOY,
+    group: BuildCommandGroup.Deploy,
     type: 'boolean',
   },
   serve: {
     describe: 'Start development server',
-    group: NAME_GROUP_SERVE,
+    group: BuildCommandGroup.Serve,
     type: 'boolean',
   },
   port: {
     alias: 'p',
     describe: 'Development server port',
-    group: NAME_GROUP_SERVE,
+    group: BuildCommandGroup.Serve,
     type: 'number',
     defaultDescription: '8000',
     implies: 'serve',
@@ -176,31 +190,35 @@ const opts = Object.freeze({
   host: {
     alias: 'h',
     describe: 'Development server host',
-    group: NAME_GROUP_SERVE,
+    group: BuildCommandGroup.Serve,
     type: 'string',
     nargs: 1,
     requiresArg: true,
     implies: 'serve',
     defaultDescription: 'localhost',
   },
-}) satisfies Record<string, Options>;
+} as const satisfies Record<string, Options>;
 
 type BuildOptions = InferredOptionTypes<typeof opts>;
 
 export default {
   command: 'build',
-  describe: 'Build Appium extension documentation',
-  builder: (yargs) =>
-    yargs.options(opts).check((argv) => {
-      // either this method doesn't provide camel-cased props, or the types are wrong.
-      if (argv.deploy === true && argv['site-dir']) {
-        log.error(
-          `--site-dir is unsupported when running "${NAME_BIN} deploy"; use --prefix if needd, but remember that the default behavior is to deploy to the root of the branch (${argv.branch}) instead of a subdirectory`
-        );
-        return false;
-      }
-      return true;
-    }),
+  describe: 'Build Appium extension documentation using TypeDoc & MkDocs',
+  builder(yargs) {
+    return yargs
+      .options(opts)
+      .check(async (argv) => {
+        // either this method doesn't provide camel-cased props, or the types are wrong.
+        if (argv.deploy === true && argv['site-dir']) {
+          return `--site-dir is unsupported when running "${NAME_BIN} deploy"; use --prefix if needed, but remember that the default behavior is to deploy to the root of the branch (${argv.branch}) instead of a subdirectory`;
+        }
+
+        return await checkMissingPaths(opts, BuildCommandGroup.BuildPaths, argv);
+      })
+      .epilog(
+        'For help with further configuration, see:\n  - MkDocs: https://www.mkdocs.org\n  - TypeDoc: https://typedoc.org\n  - Mike: https://github.com/jimporter/mike'
+      );
+  },
   async handler(args) {
     const stop = stopwatch('build');
     log.debug('Build command called with args: %O', args);
@@ -223,4 +241,4 @@ export default {
     }
     log.success('Done! (total: %dms)', stop());
   },
-} as CommandModule<{}, BuildOptions>;
+} as CommandModule<object, BuildOptions>;

package/lib/cli/command/index.ts

@@ -1,3 +1,8 @@
+/**
+ * Exports all command modules
+ * @module
+ */
+
 export {default as init} from './init';
 export {default as validate} from './validate';
 export {default as build} from './build';

package/lib/cli/command/init.ts

@@ -1,19 +1,32 @@
+/**
+ * Yargs command module for the `init` command.
+ * @module
+ */
+
 import _ from 'lodash';
-import {CommandModule, InferredOptionTypes, Options} from 'yargs';
+import type {CommandModule, InferredOptionTypes, Options} from 'yargs';
 import {init} from '../../init';
 import logger from '../../logger';
 import {stopwatch} from '../../util';
+import {checkMissingPaths} from '../check';
 
 const log = logger.withTag('init');
 
-const NAME_GROUP_INIT_MKDOCS = 'MkDocs Config:';
-const NAME_GROUP_INIT_PATHS = 'Paths:';
-const NAME_GROUP_INIT_BEHAVIOR = 'Initialization Behavior:';
+enum InitCommandGroup {
+  MkDocs = 'MkDocs Config:',
+  Paths = 'Custom Paths:',
+  Behavior = 'Initialization Behavior:',
+}
 
-const opts = Object.freeze({
+/**
+ * Note the groups here; _some_ opts are paths and would usually be checked via
+ * {@linkcode checkMissingPaths}, but in this case we do not care if the path exists or not, because
+ * we may create it.
+ */
+const opts = {
   copyright: {
     description: 'Copyright notice',
-    group: NAME_GROUP_INIT_MKDOCS,
+    group: InitCommandGroup.MkDocs,
     nargs: 1,
     requiresArg: true,
     type: 'string',
@@ -22,19 +35,19 @@ const opts = Object.freeze({
     default: '.',
     defaultDescription: '(current directory)',
     description: 'Directory of package',
-    group: NAME_GROUP_INIT_PATHS,
+    group: InitCommandGroup.Paths,
     normalize: true,
     type: 'string',
   },
   'dry-run': {
     describe: 'Do not write any files; show what would be done',
-    group: NAME_GROUP_INIT_BEHAVIOR,
+    group: InitCommandGroup.Behavior,
     type: 'boolean',
   },
   force: {
     alias: 'f',
     describe: 'Overwrite existing configurations',
-    group: NAME_GROUP_INIT_BEHAVIOR,
+    group: InitCommandGroup.Behavior,
     type: 'boolean',
   },
   include: {
@@ -43,19 +56,20 @@ const opts = Object.freeze({
     coerce: (value: string | string[]) => _.castArray(value),
     description: 'Files to include in compilation (globs OK)',
     nargs: 1,
+    group: InitCommandGroup.MkDocs,
     requiresArg: true,
     type: 'string',
   },
   mkdocs: {
     default: true,
     description: 'Create mkdocs.yml if needed',
-    group: NAME_GROUP_INIT_BEHAVIOR,
+    group: InitCommandGroup.Behavior,
     type: 'boolean',
   },
   'mkdocs-yml': {
     defaultDescription: './mkdocs.yml',
-    description: 'Path to mkdocs.yml',
-    group: NAME_GROUP_INIT_PATHS,
+    description: 'Path to new or existing mkdocs.yml',
+    group: InitCommandGroup.MkDocs,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -63,8 +77,8 @@ const opts = Object.freeze({
   },
   'package-json': {
     defaultDescription: './package.json',
-    describe: 'Path to package.json',
-    group: NAME_GROUP_INIT_PATHS,
+    describe: 'Path to existing package.json',
+    group: InitCommandGroup.Paths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -73,13 +87,13 @@ const opts = Object.freeze({
   python: {
     default: true,
     description: 'Install Python dependencies if needed',
-    group: NAME_GROUP_INIT_BEHAVIOR,
+    group: InitCommandGroup.Behavior,
     type: 'boolean',
   },
   'python-path': {
     defaultDescription: '(derived from shell)',
     description: 'Path to python 3 executable',
-    group: NAME_GROUP_INIT_PATHS,
+    group: InitCommandGroup.Paths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -88,7 +102,7 @@ const opts = Object.freeze({
   'repo-name': {
     defaultDescription: '(derived from --repo-url)',
     description: 'Name of extension repository',
-    group: NAME_GROUP_INIT_MKDOCS,
+    group: InitCommandGroup.MkDocs,
     nargs: 1,
     requiresArg: true,
     type: 'string',
@@ -96,7 +110,7 @@ const opts = Object.freeze({
   'repo-url': {
     defaultDescription: '(from package.json)',
     description: 'URL of extension repository',
-    group: NAME_GROUP_INIT_MKDOCS,
+    group: InitCommandGroup.MkDocs,
     nargs: 1,
     requiresArg: true,
     type: 'string',
@@ -104,7 +118,7 @@ const opts = Object.freeze({
   'site-description': {
     defaultDescription: '(from package.json)',
     description: 'Site description',
-    group: NAME_GROUP_INIT_MKDOCS,
+    group: InitCommandGroup.MkDocs,
     nargs: 1,
     requiresArg: true,
     type: 'string',
@@ -112,15 +126,15 @@ const opts = Object.freeze({
   'site-name': {
     defaultDescription: '(extension package name)',
     description: 'Name of site',
-    group: NAME_GROUP_INIT_MKDOCS,
+    group: InitCommandGroup.MkDocs,
     nargs: 1,
     requiresArg: true,
     type: 'string',
   },
   'tsconfig-json': {
     defaultDescription: './tsconfig.json',
-    describe: 'Path to tsconfig.json',
-    group: NAME_GROUP_INIT_PATHS,
+    describe: 'Path to new or existing tsconfig.json',
+    group: InitCommandGroup.Behavior,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -129,13 +143,13 @@ const opts = Object.freeze({
   typedoc: {
     default: true,
     description: 'Create typedoc.json if needed',
-    group: NAME_GROUP_INIT_BEHAVIOR,
+    group: InitCommandGroup.Behavior,
     type: 'boolean',
   },
   'typedoc-json': {
     defaultDescription: './typedoc.json',
-    describe: 'Path to typedoc.json',
-    group: NAME_GROUP_INIT_PATHS,
+    describe: 'Path to new or existing typedoc.json',
+    group: InitCommandGroup.Behavior,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -144,20 +158,31 @@ const opts = Object.freeze({
   typescript: {
     default: true,
     description: 'Create tsconfig.json if needed',
-    group: NAME_GROUP_INIT_BEHAVIOR,
+    group: InitCommandGroup.Behavior,
+    type: 'boolean',
+  },
+  upgrade: {
+    alias: 'up',
+    describe: 'Only upgrade Python dependencies if out-of-date',
+    group: InitCommandGroup.Behavior,
     type: 'boolean',
+    conflicts: 'force',
   },
-}) satisfies Record<string, Options>;
+} as const satisfies Record<string, Options>;
 
 type InitOptions = InferredOptionTypes<typeof opts>;
 
 export default {
   command: 'init',
   describe: 'Initialize package for doc generation',
-  builder: opts,
+  builder(yargs) {
+    return yargs
+      .options(opts)
+      .check(async (argv) => checkMissingPaths(opts, InitCommandGroup.Paths, argv));
+  },
   async handler(args) {
     const done = stopwatch('init');
     await init({...args, overwrite: args.force, cwd: args.dir});
     log.success('Done (%dms)', done());
   },
-} as CommandModule<{}, InitOptions>;
+} as CommandModule<object, InitOptions>;