@appium/docutils 0.2.2 → 0.3.1

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

package/lib/constants.ts

@@ -86,6 +86,11 @@ export const NAME_ERR_ENOENT = 'ENOENT';
  */
 export const NAME_ERR_EEXIST = 'EEXIST';
 
+/**
+ * Name of the default theme
+ */
+export const NAME_THEME = 'material';
+
 /**
  * Default log level
  */

package/lib/error.ts

@@ -1 +1,7 @@
+/**
+ * A custom error class. This exists so we can use `instanceof` to differentiate between "expected"
+ * exceptions and unexpected ones.
+ * @module
+ */
+
 export class DocutilsError extends Error {}

package/lib/fs.ts

@@ -127,7 +127,10 @@ async function _readPkgJson(
   cwd: string,
   normalize: true
 ): Promise<{pkgPath: string; pkg: NormalizedPackageJson}>;
-async function _readPkgJson(cwd: string): Promise<{pkgPath: string; pkg: PackageJson}>;
+async function _readPkgJson(
+  cwd: string,
+  normalize?: false
+): Promise<{pkgPath: string; pkg: PackageJson}>;
 async function _readPkgJson(
   cwd: string,
   normalize?: boolean
@@ -236,14 +239,14 @@ export const whichMike = _.partial(cachedWhich, NAME_MIKE);
  */
 export const readMkDocsYml = _.memoize(
   async (filepath: string, cwd = process.cwd()): Promise<MkDocsYml> => {
-    let mkDocsYml = <MkDocsYml>await readYaml(filepath);
+    let mkDocsYml = (await readYaml(filepath)) as MkDocsYml;
     if (mkDocsYml.site_dir) {
       mkDocsYml.site_dir = path.resolve(cwd, path.dirname(filepath), mkDocsYml.site_dir);
     }
     if (mkDocsYml.INHERIT) {
       let inheritPath: string | undefined = path.resolve(path.dirname(filepath), mkDocsYml.INHERIT);
       while (inheritPath) {
-        const inheritYml = <MkDocsYml>await readYaml(inheritPath);
+        const inheritYml = (await readYaml(inheritPath)) as MkDocsYml;
         if (inheritYml.site_dir) {
           inheritYml.site_dir = path.resolve(path.dirname(inheritPath), inheritYml.site_dir);
           log.debug('Resolved site_dir to %s', inheritYml.site_dir);

package/lib/index.ts

@@ -1,3 +1,8 @@
+/**
+ * Main entry point
+ * @module
+ */
+
 export * from './mike';
 export * from './builder';
 export * from './validate';

package/lib/init.ts

@@ -126,7 +126,9 @@ export const initMkDocs = createScaffoldTask<InitMkDocsOptions, MkDocsYml>(
       if (repoUrl && !repoName) {
         let {pathname} = new URL(repoUrl);
         pathname = pathname.slice(1);
-        let [owner, repo] = pathname.split('/');
+        const pathparts = pathname.split('/');
+        const owner = pathparts[0];
+        let repo = pathparts[1];
         repo = repo.replace(/\.git$/, '');
         repoName = [owner, repo].join('/');
         if (repoName) {
@@ -158,8 +160,12 @@ export const initMkDocs = createScaffoldTask<InitMkDocsOptions, MkDocsYml>(
 export async function initPython({
   pythonPath = NAME_PYTHON,
   dryRun = false,
+  upgrade = false,
 }: InitPythonOptions = {}): Promise<void> {
   const args = ['-m', 'pip', 'install', '-r', REQUIREMENTS_TXT_PATH];
+  if (upgrade) {
+    args.push('--upgrade');
+  }
   if (dryRun) {
     dryRunLog.info('Would execute command: %s %s', pythonPath, args.join(' '));
   } else {
@@ -214,6 +220,7 @@ export async function init({
   dryRun,
   cwd,
   pythonPath,
+  upgrade,
   typedocJson: typeDocJsonPath,
 }: InitOptions = {}): Promise<void> {
   if (!typescript && typedoc) {
@@ -222,7 +229,7 @@ export async function init({
     );
   }
 
-  if (typescript) {
+  if (typescript && !upgrade) {
     await initTsConfigJson({
       dest: tsconfigJsonPath,
       packageJson: packageJsonPath,
@@ -233,7 +240,7 @@ export async function init({
     });
   }
 
-  if (typedoc) {
+  if (typedoc && !upgrade) {
     await initTypeDocJson({
       dest: typeDocJsonPath,
       packageJson: packageJsonPath,
@@ -244,10 +251,10 @@ export async function init({
   }
 
   if (python) {
-    await initPython({pythonPath, dryRun});
+    await initPython({pythonPath, dryRun, upgrade});
   }
 
-  if (mkdocs) {
+  if (mkdocs && !upgrade) {
     await initMkDocs({
       dest: mkdocsYmlPath,
       cwd,
@@ -262,7 +269,7 @@ export async function init({
   }
 }
 
-export interface InitTypeDocOptions extends ScaffoldTaskOptions {}
+export type InitTypeDocOptions = ScaffoldTaskOptions;
 export interface InitTsConfigOptions extends ScaffoldTaskOptions {
   /**
    * List of source files (globs supported); typically `src` or `lib`
@@ -274,6 +281,11 @@ export interface InitPythonOptions extends ScaffoldTaskOptions {
    * Path to `python` (v3.x) executable
    */
   pythonPath?: string;
+
+  /**
+   * If true, upgrade only
+   */
+  upgrade?: boolean;
 }
 
 /**
@@ -315,5 +327,10 @@ export type InitOptions = Simplify<
      * Path to new or existing `mkdocs.yml` file
      */
     mkdocsYml?: string;
+
+    /**
+     * If `true`, upgrade only
+     */
+    upgrade?: boolean;
   }
 >;

package/lib/logger.ts

@@ -134,7 +134,7 @@ class DocutilsReporter extends FancyReporter {
  *
  * "Global" inasmuch as any logger created from the root logger will use this level.
  */
-let globalLevel = LogLevelMap[DEFAULT_LOG_LEVEL];
+let globalLevel: LogLevel = LogLevelMap[DEFAULT_LOG_LEVEL];
 
 /**
  * The logger from which all loggers are created.  This one uses a unique tag and our custom reporter.

package/lib/mike.js

@@ -1,3 +1,8 @@
+/**
+ * API around `mike`, a tool for deploying multiple versions of MkDocs-built sites to GitHub Pages
+ * @module
+ */
+
 import {exec} from 'teen_process';
 // eslint-disable-next-line import/no-unresolved
 import log from './logger';

package/lib/util.ts

@@ -4,6 +4,7 @@
  */
 
 import _ from 'lodash';
+import {SpawnOptions, spawn} from 'node:child_process';
 import path from 'node:path';
 import type {SubProcess} from 'teen_process';
 
@@ -32,6 +33,9 @@ export function stopwatch(id: string) {
 }
 stopwatch.cache = new Map<string, number>();
 
+/**
+ * Converts a tuple to an object; use for extracting parameter types from a function signature
+ */
 export type TupleToObject<
   T extends readonly any[],
   M extends Record<Exclude<keyof T, keyof any[]>, PropertyKey>
@@ -69,8 +73,27 @@ export const argify: (obj: Record<string, string | number | boolean | undefined>
   );
 
 /**
- * Conversion of the parameters of {@linkcode Subprocess.start} to an object.
+ * 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.
+ * @param command Command to run
+ * @param args Args to pass to command
+ * @param opts Spawn options. `{stdio: 'inherit'}` will always be true
+ * @privateRemarks `teen_process` is good for running a one-shot command, but not so great for
+ * background tasks; we use node's `child_process` directly here to pass `stdio` through, since
+ * `teen_process` basically does not respect `{stdio: 'inherit'}`.
  */
-export type TeenProcessSubprocessStartOpts = Partial<
-  TupleToObject<Parameters<SubProcess['start']>, ['startDetector', 'detach', 'timeoutMs']>
->;
+export async function spawnBackgroundProcess(command: string, args: string[], opts: SpawnOptions) {
+  return new Promise<void>((resolve, reject) => {
+    spawn(command, args, {...opts, stdio: 'inherit'})
+      .on('error', reject)
+      .on('close', (code) => {
+        // can be null or number
+        if (code) {
+          return reject(new Error(`${command} exited with code ${code}`));
+        }
+        resolve();
+      });
+  });
+}
+
+export type SpawnBackgroundProcessOpts = Omit<SpawnOptions, 'stdio'>;

package/lib/validate.ts

@@ -1,15 +1,14 @@
 /**
- * Validates an environment for building documentation
+ * Validates an environment for building documentation; used by `validate` command
  *
  * @module
  */
 
-import {fs} from '@appium/support';
+import {fs, util} from '@appium/support';
 import chalk from 'chalk';
 import _ from 'lodash';
 import {EventEmitter} from 'node:events';
 import path from 'node:path';
-import pluralize from 'pluralize';
 import {satisfies} from 'semver';
 import {exec} from 'teen_process';
 import {
@@ -36,7 +35,6 @@ import {
   findMkDocsYml,
   readJson5,
   readTypedocJson,
-  readYaml,
   whichMkDocs,
   whichNpm,
   whichPython,
@@ -287,7 +285,7 @@ export class DocutilsValidator extends EventEmitter {
       return this.requirementsTxt;
     }
 
-    let requiredPackages: PipPackage[] = [];
+    const requiredPackages: PipPackage[] = [];
 
     try {
       let requirementsTxt = await fs.readFile(REQUIREMENTS_TXT_PATH, 'utf8');
@@ -312,6 +310,9 @@ export class DocutilsValidator extends EventEmitter {
     this.emittedErrors.clear();
   }
 
+  /**
+   * Validates that the correct version of `mkdocs` is installed
+   */
   protected async validateMkDocs() {
     let mkDocsPath: string | undefined;
     try {
@@ -466,7 +467,7 @@ export class DocutilsValidator extends EventEmitter {
     const msgParts = [];
     if (missingPackages.length) {
       msgParts.push(
-        `The following required ${pluralize(
+        `The following required ${util.pluralize(
           'package',
           missingPackages.length
         )} could not be found:\n${missingPackages
@@ -476,7 +477,7 @@ export class DocutilsValidator extends EventEmitter {
     }
     if (invalidVersionPackages.length) {
       msgParts.push(
-        `The following required ${pluralize(
+        `The following required ${util.pluralize(
           'package',
           invalidVersionPackages.length
         )} are installed, but at the wrong version:\n${invalidVersionPackages
@@ -533,7 +534,7 @@ export class DocutilsValidator extends EventEmitter {
     }
 
     if (rawTypeDocVersion) {
-      let match = rawTypeDocVersion.match(TYPEDOC_VERSION_REGEX);
+      const match = rawTypeDocVersion.match(TYPEDOC_VERSION_REGEX);
       if (match) {
         typeDocVersion = match[1];
       } else {
@@ -621,7 +622,7 @@ export class DocutilsValidator extends EventEmitter {
       return this.fail(`Could not find TypeScript compiler ("tsc") from ${pkgDir}`);
     }
 
-    let match = rawTypeScriptVersion.match(TYPESCRIPT_VERSION_REGEX);
+    const match = rawTypeScriptVersion.match(TYPESCRIPT_VERSION_REGEX);
     if (match) {
       typeScriptVersion = match[1];
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/docutils",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Documentation generation utilities for Appium and related projects",
   "keywords": [
     "automation",
@@ -46,31 +46,29 @@
     "test:e2e": "echo \"No e2e tests for this package\"",
     "test:smoke": "node ./index.js",
     "test:unit": "mocha \"./test/unit/**/*.spec.js\"",
-    "start": "node ./build/lib/cli.js"
+    "start": "node ./build/lib/cli/index.js"
   },
   "dependencies": {
-    "@appium/support": "^3.1.6",
+    "@appium/support": "^3.1.8",
     "@appium/tsconfig": "^0.2.4",
-    "@appium/typedoc-plugin-appium": "^0.5.0",
+    "@appium/typedoc-plugin-appium": "^0.5.2",
     "@sliphua/lilconfig-ts-loader": "3.2.2",
     "chalk": "4.1.2",
     "consola": "2.15.3",
     "diff": "5.1.0",
     "figures": "3.2.0",
     "find-up": "5.0.0",
-    "glob": "8.1.0",
     "json5": "2.2.3",
-    "lilconfig": "2.0.6",
+    "lilconfig": "2.1.0",
     "lodash": "4.17.21",
     "log-symbols": "4.1.0",
     "pkg-dir": "5.0.0",
-    "pluralize": "8.0.0",
     "read-pkg": "5.2.0",
     "semver": "7.3.8",
     "source-map-support": "0.5.21",
     "teen_process": "2.0.2",
-    "type-fest": "3.6.0",
-    "typedoc": "0.23.25",
+    "type-fest": "3.7.1",
+    "typedoc": "0.23.28",
     "typedoc-plugin-markdown": "3.14.0",
     "typedoc-plugin-resolve-crossmodule-references": "0.3.3",
     "typescript": "4.9.5",
@@ -85,5 +83,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7b4935632222123a4fa7422461f6312f1f0dfbe4"
+  "gitHead": "d514ebdd7ebd27bb236509d0a3d580f0f18a34e5"
 }

package/requirements.txt

@@ -1,4 +1,4 @@
 mkdocs==1.4.2
-mkdocs-material==9.0.14
+mkdocs-material==9.1.4
 mkdocs-material-extensions==1.1.1
 mike==1.1.2