@appium/docutils 0.2.1 → 0.3.0

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:',
+}
 
+/**
+ * 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 = {
     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 = {
     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 = {
   },
   '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 = {
   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 = {
   '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 = {
   '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 = {
   '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 = {
   '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 = {
   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,23 +158,31 @@ const opts = {
   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',
   },
-} as const;
-opts as Record<string, Options>; // type check
+} as const satisfies Record<string, Options>;
 
 type InitOptions = InferredOptionTypes<typeof opts>;
 
-const initCommand: CommandModule<{}, InitOptions> = {
+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());
   },
-};
-
-export default initCommand;
+} 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 = {
   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 = {
   '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 = {
   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 = {
   '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 = {
   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,24 +84,25 @@ const opts = {
   typescript: {
     default: true,
     description: 'Validate TypeScript environment',
-    group: NAME_GROUP_VALIDATE,
+    group: ValidateCommandGroup.Behavior,
     type: 'boolean',
   },
-} as const;
-opts as Record<string, Options>;
+} as const satisfies Record<string, Options>;
+
 type ValidateOptions = InferredOptionTypes<typeof opts>;
-const validateCommand: CommandModule<{}, ValidateOptions> = {
+
+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[]) => {
@@ -113,10 +122,8 @@ const validateCommand: CommandModule<{}, ValidateOptions> = {
 
     if (errorCount) {
       throw new DocutilsError(
-        `Validation failed with ${errorCount} ${pluralize('error', errorCount)}`
+        `Validation failed with ${errorCount} ${util.pluralize('error', errorCount)}`
       );
     }
   },
-};
-
-export default validateCommand;
+} 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

@@ -32,34 +32,34 @@ class DocutilsReporter extends FancyReporter {
   /**
    * Mapping of log types (the name of the logging method called) to chalk fg colors
    */
-  static TYPE_COLOR_MAP = {
+  static readonly TYPE_COLOR_MAP = {
     info: 'cyan',
     success: 'green',
     error: 'red',
     warn: 'yellow',
-  } as const;
+  } satisfies {[k in LogType]?: typeof ForegroundColor};
 
   /**
    * Mapping of log levels to chalk fg colors
    */
-  static LEVEL_COLORS = {
+  static readonly LEVEL_COLORS = {
     0: 'red',
     1: 'yellow',
     2: 'white',
     3: 'green',
-  } as const;
+  } satisfies {[k in LogLevel]?: typeof ForegroundColor};
 
   /**
    * Mapping of log types to icons/symbols
    */
-  static TYPE_ICONS = {
+  static readonly TYPE_ICONS = {
     info: logSymbols.info,
     success: logSymbols.success,
     error: logSymbols.error,
     warn: logSymbols.warning,
     debug: figures('›'),
     trace: figures('›'),
-  } as const;
+  } satisfies {[k in LogType]?: string};
 
   /**
    * Default color to use if we can't find a color for the log type or level
@@ -191,8 +191,3 @@ function createLogProxy(logger: Consola): Consola {
  * @see {createLogProxy}
  */
 export default rootLogger;
-
-// these are just type-sanity checks
-<{[k in LogType]?: typeof ForegroundColor}>DocutilsReporter.TYPE_COLOR_MAP;
-<{[k in LogLevel]?: typeof ForegroundColor}>DocutilsReporter.LEVEL_COLORS;
-<{[k in LogType]?: string}>DocutilsReporter.TYPE_ICONS;

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

@@ -9,16 +9,10 @@ import type {TypeDocOptions} from 'typedoc';
 
 /**
  * A `tsconfig.json` file w/ `$schema` prop
- *
- * Due to some `unknown` types in {@linkcode type-fest.TsConfigJson}, we cannot use that type
- * directly and need to use `Jsonify`.
- *
  */
-export type TsConfigJson = Jsonify<
-  TsConfigJsonBase & {
-    $schema?: string;
-  }
->;
+export type TsConfigJson = TsConfigJsonBase & {
+  $schema?: string;
+};
 
 /**
  * A `typedoc.json` file w/ `$schema` and `extends` props

package/lib/util.ts

@@ -32,6 +32,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,7 +72,7 @@ export const argify: (obj: Record<string, string | number | boolean | undefined>
   );
 
 /**
- * Conversion of the parameters of {@linkcode Subprocess.start} to an object.
+ * Conversion of the parameters of {@linkcode SubProcess.start} to an object.
  */
 export type TeenProcessSubprocessStartOpts = Partial<
   TupleToObject<Parameters<SubProcess['start']>, ['startDetector', 'detach', 'timeoutMs']>