@appium/docutils 0.2.2 → 0.3.0

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>;

package/lib/cli/command/validate.ts

@@ -1,25 +1,33 @@
-import pluralize from 'pluralize';
-import {CommandModule, InferredOptionTypes, Options} from 'yargs';
+/**
+ * Yargs command module for the `validate` command.
+ * @module
+ */
+
+import {util} from '@appium/support';
+import type {CommandModule, InferredOptionTypes, Options} from 'yargs';
 import {DocutilsError} from '../../error';
 import {DocutilsValidator, ValidationKind} from '../../validate';
 import logger from '../../logger';
+import {checkMissingPaths} from '../check';
 
 const log = logger.withTag('validate');
 
-const NAME_GROUP_VALIDATE = 'Validation Behavior:';
-const NAME_GROUP_VALIDATE_PATHS = 'Paths:';
+enum ValidateCommandGroup {
+  Behavior = 'Validation Behavior:',
+  Paths = 'Custom Paths:',
+}
 
-const opts = Object.freeze({
+const opts = {
   mkdocs: {
     default: true,
     description: 'Validate MkDocs environment',
-    group: NAME_GROUP_VALIDATE,
+    group: ValidateCommandGroup.Behavior,
     type: 'boolean',
   },
   'mkdocs-yml': {
     defaultDescription: './mkdocs.yml',
     description: 'Path to mkdocs.yml',
-    group: NAME_GROUP_VALIDATE_PATHS,
+    group: ValidateCommandGroup.Paths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -28,7 +36,7 @@ const opts = Object.freeze({
   'npm-path': {
     defaultDescription: '(derived from shell)',
     description: 'Path to npm executable',
-    group: NAME_GROUP_VALIDATE_PATHS,
+    group: ValidateCommandGroup.Paths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -37,13 +45,13 @@ const opts = Object.freeze({
   python: {
     default: true,
     description: 'Validate Python 3 environment',
-    group: NAME_GROUP_VALIDATE,
+    group: ValidateCommandGroup.Behavior,
     type: 'boolean',
   },
   'python-path': {
     defaultDescription: '(derived from shell)',
     description: 'Path to python 3 executable',
-    group: NAME_GROUP_VALIDATE_PATHS,
+    group: ValidateCommandGroup.Paths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -52,7 +60,7 @@ const opts = Object.freeze({
   'tsconfig-json': {
     defaultDescription: './tsconfig.json',
     describe: 'Path to tsconfig.json',
-    group: NAME_GROUP_VALIDATE_PATHS,
+    group: ValidateCommandGroup.Paths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -61,13 +69,13 @@ const opts = Object.freeze({
   typedoc: {
     default: true,
     description: 'Validate TypoDoc environment',
-    group: NAME_GROUP_VALIDATE,
+    group: ValidateCommandGroup.Behavior,
     type: 'boolean',
   },
   'typedoc-json': {
     defaultDescription: './typedoc.json',
     describe: 'Path to typedoc.json',
-    group: NAME_GROUP_VALIDATE_PATHS,
+    group: ValidateCommandGroup.Paths,
     nargs: 1,
     normalize: true,
     requiresArg: true,
@@ -76,25 +84,25 @@ const opts = Object.freeze({
   typescript: {
     default: true,
     description: 'Validate TypeScript environment',
-    group: NAME_GROUP_VALIDATE,
+    group: ValidateCommandGroup.Behavior,
     type: 'boolean',
   },
-}) satisfies Record<string, Options>;
+} as const satisfies Record<string, Options>;
 
 type ValidateOptions = InferredOptionTypes<typeof opts>;
 
 export default {
   command: 'validate',
   describe: 'Validate Environment',
-  builder: opts,
+  builder(yargs) {
+    return yargs.options(opts).check(async (argv) => {
+      if (!argv.python && !argv.typedoc && !argv.typescript && !argv.mkdocs) {
+        return 'No validation targets specified; one or more of --python, --typescript, --typedoc or --mkdocs must be provided';
+      }
+      return checkMissingPaths(opts, ValidateCommandGroup.Paths, argv);
+    });
+  },
   async handler(args) {
-    if (!args.python && !args.typedoc && !args.typescript && !args.mkdocs) {
-      // specifically not a DocutilsError
-      throw new Error(
-        'No validation targets specified; one or more of --python, --typescript, --typedoc or --mkdocs must be provided'
-      );
-    }
-
     let errorCount = 0;
     const validator = new DocutilsValidator(args)
       .once(DocutilsValidator.BEGIN, (kinds: ValidationKind[]) => {
@@ -114,8 +122,8 @@ export default {
 
     if (errorCount) {
       throw new DocutilsError(
-        `Validation failed with ${errorCount} ${pluralize('error', errorCount)}`
+        `Validation failed with ${errorCount} ${util.pluralize('error', errorCount)}`
       );
     }
   },
-} as CommandModule<{}, ValidateOptions>;
+} as CommandModule<object, ValidateOptions>;

package/lib/cli/index.ts

@@ -1,4 +1,11 @@
 #!/usr/bin/env node
+/* eslint-disable no-console */
+
+/**
+ * Main CLI entry point for `@appium/docutils`
+ * @module
+ */
+
 import logger from '../logger';
 
 import _ from 'lodash';
@@ -8,6 +15,10 @@ import {DEFAULT_LOG_LEVEL, LogLevelMap, NAME_BIN} from '../constants';
 import {DocutilsError} from '../error';
 import {build, init, validate} from './command';
 import {findConfig} from './config';
+import {fs} from '@appium/support';
+import {sync as readPkg} from 'read-pkg';
+
+const pkg = readPkg({cwd: fs.findRoot(__dirname)});
 
 const log = logger.withTag('cli');
 export async function main(argv = hideBin(process.argv)) {
@@ -45,7 +56,7 @@ export async function main(argv = hideBin(process.argv)) {
         describe: 'Disable config file discovery',
       },
     })
-    .middleware(
+    .middleware([
       /**
        * Configures logging; `--verbose` implies `--log-level=debug`
        */
@@ -55,8 +66,15 @@ export async function main(argv = hideBin(process.argv)) {
           log.debug('Debug logging enabled via --verbose');
         }
         log.level = LogLevelMap[argv.logLevel];
-      }
-    )
+      },
+      /**
+       * Writes a startup message, if logging is enabled
+       */
+      async () => {
+        log.info(`${pkg.name} @ v${pkg.version} (Node.js ${process.version})`);
+      },
+    ])
+    .epilog(`Please report bugs at ${pkg.bugs?.url}`)
     .fail(
       /**
        * Custom failure handler so we can log nicely.
@@ -67,6 +85,7 @@ export async function main(argv = hideBin(process.argv)) {
           log.error(error.message);
         } else {
           y.showHelp();
+          console.log();
           log.error(msg ?? error.message);
         }
         y.exit(1, error);
@@ -81,7 +100,7 @@ export async function main(argv = hideBin(process.argv)) {
 }
 
 if (require.main === module) {
-  // eslint-disable-next-line promise/prefer-await-to-then
+  // eslint-disable-next-line promise/prefer-await-to-then, promise/prefer-await-to-callbacks
   main().catch((err) => {
     log.error('Caught otherwise-unhandled rejection (this is probably a bug):', err);
   });