@appium/docutils 0.3.10 → 0.3.12

package/lib/fs.ts

@@ -3,27 +3,26 @@
  * @module
  */
 
-import findUp from 'find-up';
-import YAML from 'yaml';
-import readPkg, {NormalizedPackageJson, PackageJson} from 'read-pkg';
-import path from 'node:path';
-import {JsonValue} from 'type-fest';
 import {fs} from '@appium/support';
+import findUp from 'find-up';
 import * as JSON5 from 'json5';
 import _ from 'lodash';
+import path from 'node:path';
 import _pkgDir from 'pkg-dir';
-import {getLogger} from './logger';
+import readPkg, {NormalizedPackageJson, PackageJson} from 'read-pkg';
+import {JsonValue} from 'type-fest';
 import {Application, TypeDocReader} from 'typedoc';
+import YAML from 'yaml';
 import {
-  NAME_TYPEDOC_JSON,
   NAME_MKDOCS_YML,
-  NAME_PACKAGE_JSON,
-  NAME_MKDOCS,
   NAME_NPM,
+  NAME_PACKAGE_JSON,
   NAME_PYTHON,
-  NAME_MIKE,
+  NAME_TYPEDOC,
+  NAME_TYPEDOC_JSON,
 } from './constants';
 import {DocutilsError} from './error';
+import {getLogger} from './logger';
 import {MkDocsYml} from './model';
 
 const log = getLogger('fs');
@@ -207,27 +206,49 @@ export function safeWriteFile(filepath: string, content: JsonValue, overwrite =
 /**
  * `which` with memoization
  */
-export const cachedWhich = _.memoize(fs.which);
+const cachedWhich = _.memoize(fs.which as typeof import('which'));
 
 /**
- * Finds `mkdocs` executable
+ * Finds `npm` executable
  */
-export const whichMkDocs = _.partial(cachedWhich, NAME_MKDOCS);
+export const whichNpm = _.partial(cachedWhich, NAME_NPM, {nothrow: true});
 
 /**
- * Finds `npm` executable
+ * Finds `python` executable
  */
-export const whichNpm = _.partial(cachedWhich, NAME_NPM);
+const whichPython = _.partial(cachedWhich, NAME_PYTHON, {nothrow: true});
 
 /**
- * Finds `python` executable
+ * Finds `python3` executable
  */
-export const whichPython = _.partial(cachedWhich, NAME_PYTHON);
+const whichPython3 = _.partial(cachedWhich, `${NAME_PYTHON}3`, {nothrow: true});
 
 /**
- * Finds `mike` executable
+ * Finds `typedoc` executable
  */
-export const whichMike = _.partial(cachedWhich, NAME_MIKE);
+const whichTypeDoc = _.partial(cachedWhich, NAME_TYPEDOC, {nothrow: true});
+
+/**
+ * Finds the `typedoc` executable.
+ *
+ * Looks in the `node_modules/.bin` dir from the current working directory, and if this fails, in the `node_modules` dir for the file which `.bin/typedoc` should be a symlink of, and if _that_ fails, try the `PATH`.
+ */
+export const findTypeDoc = _.memoize(async (cwd = process.cwd()): Promise<string | undefined> => {
+  // .cmd is for win32, of course. note that glob _always_ uses posix dir separators.
+  const globResult =
+    (await fs.glob('node_modules/.bin/typedoc?(.cmd)', {cwd, nodir: true})) ??
+    (await fs.glob('node_modules/**/typedoc/bin/typedoc', {cwd, nodir: true, follow: true}));
+  return _.first(globResult) ?? (await whichTypeDoc());
+});
+
+/**
+ * Finds the `python3` or `python` executable in the user's `PATH`.
+ *
+ * `python3` is preferred over `python`, since the latter could be Python 2.
+ */
+export const findPython = _.memoize(
+  async (): Promise<string | undefined> => (await whichPython3()) ?? (await whichPython())
+);
 
 /**
  * Reads an `mkdocs.yml` file, merges inherited configs, and returns the result. The result is cached.

package/lib/init.ts

@@ -20,7 +20,7 @@ import {createScaffoldTask, ScaffoldTaskOptions} from './scaffold';
 import {getLogger} from './logger';
 import {MkDocsYml, TsConfigJson, TypeDocJson} from './model';
 import _ from 'lodash';
-import {stringifyJson5, stringifyYaml} from './fs';
+import {findPython, stringifyJson5, stringifyYaml} from './fs';
 
 /**
  * Data for the base `mkdocs.yml` file
@@ -158,10 +158,12 @@ export const initMkDocs = createScaffoldTask<InitMkDocsOptions, MkDocsYml>(
  * @param opts Options
  */
 export async function initPython({
-  pythonPath = NAME_PYTHON,
+  pythonPath,
   dryRun = false,
   upgrade = false,
 }: InitPythonOptions = {}): Promise<void> {
+  pythonPath = pythonPath ?? (await findPython()) ?? NAME_PYTHON;
+
   const args = ['-m', 'pip', 'install', '-r', REQUIREMENTS_TXT_PATH];
   if (upgrade) {
     args.push('--upgrade');

package/lib/logger.ts

@@ -6,20 +6,19 @@
  * @module
  */
 
-import figures from 'figures';
-import logSymbols from 'log-symbols';
-import chalk, {ForegroundColor, BackgroundColor} from 'chalk';
+import chalk, {type BackgroundColor, type ForegroundColor} from 'chalk';
 import consola, {
-  logType as LogType,
-  ConsolaReporterLogObject,
+  type Consola,
+  type ConsolaReporterLogObject,
   FancyReporter,
-  FancyReporterOptions,
-  Consola,
-  ConsolaOptions,
-  LogLevel,
+  type FancyReporterOptions,
+  type LogLevel,
+  type logType as LogType,
 } from 'consola';
-import {DEFAULT_LOG_LEVEL, LogLevelMap} from './constants';
+import figures from 'figures';
 import _ from 'lodash';
+import logSymbols from 'log-symbols';
+import {DEFAULT_LOG_LEVEL, LogLevelMap} from './constants';
 
 /**
  * This is a reporter for `consola` which uses some extra/custom icons and colors.

package/lib/util.ts

@@ -6,7 +6,6 @@
 import _ from 'lodash';
 import {SpawnOptions, spawn} from 'node:child_process';
 import path from 'node:path';
-import type {SubProcess} from 'teen_process';
 
 /**
  * Computes a relative path, prepending `./`
@@ -26,7 +25,7 @@ export function stopwatch(id: string) {
   const start = Date.now();
   stopwatch.cache.set(id, start);
   return () => {
-    const result = Date.now() - stopwatch.cache.get(id)!;
+    const result = Date.now() - (stopwatch.cache.get(id) ?? 0);
     stopwatch.cache.delete(id);
     return result;
   };

package/lib/validate.ts

@@ -31,14 +31,14 @@ import {
 } from './constants';
 import {DocutilsError} from './error';
 import {
-  findPkgDir,
   findMkDocsYml,
+  findPkgDir,
+  findTypeDoc,
   readJson5,
+  readMkDocsYml,
   readTypedocJson,
-  whichMkDocs,
   whichNpm,
-  whichPython,
-  readMkDocsYml,
+  findPython,
 } from './fs';
 import {getLogger} from './logger';
 import {MkDocsYml, PipPackage, TypeDocJson} from './model';
@@ -62,7 +62,7 @@ const TYPEDOC_VERSION_REGEX = /TypeDoc\s(\d+\.\d+\..+)/;
 /**
  * Matches the MkDocs version string from `mkdocs --version`
  */
-const MKDOCS_VERSION_REGEX = /mkdocs,\s+version\s+(\d+\.\d+\.\S+)/;
+const MKDOCS_VERSION_REGEX = /\s+version\s+(\d+\.\d+\.\S+)/;
 
 const log = getLogger('validate');
 
@@ -95,12 +95,12 @@ export class DocutilsValidator extends EventEmitter {
   /**
    * Path to `npm` executable.
    */
-  protected readonly npmPath: string | undefined;
+  protected readonly npmPath?: string;
 
   /**
    * Path to `python` executable.
    */
-  protected readonly pythonPath: string | undefined;
+  protected readonly pythonPath?: string;
 
   /**
    * List of validations to perform
@@ -120,27 +120,29 @@ export class DocutilsValidator extends EventEmitter {
   /**
    * Path to `mkdocs.yml`.  If not provided, will be lazily resolved.
    */
-  protected mkDocsYmlPath: string | undefined;
+  protected mkDocsYmlPath?: string;
 
   /**
    * Path to `package.json`.  If not provided, will be lazily resolved.
    */
-  protected packageJsonPath: string | undefined;
+  protected packageJsonPath?: string;
 
   /**
    * Path to the package directory.  If not provided, will be lazily resolved.
    */
-  protected pkgDir: string | undefined;
+  protected pkgDir?: string;
 
   /**
    * Path to `tsconfig.json`.  If not provided, will be lazily resolved.
    */
-  protected tsconfigJsonPath: string | undefined;
+  protected tsconfigJsonPath?: string;
 
   /**
    * Path to `typedoc.json`.  If not provided, will be lazily resolved.
    */
-  protected typeDocJsonPath: string | undefined;
+  protected typeDocJsonPath?: string;
+
+  protected typeDocPath?: string;
 
   /**
    * Emitted when validation begins with a list of validation kinds to be performed
@@ -181,6 +183,7 @@ export class DocutilsValidator extends EventEmitter {
     this.typeDocJsonPath = opts.typedocJson;
     this.npmPath = opts.npm;
     this.mkDocsYmlPath = opts.mkdocsYml;
+    this.typeDocPath = opts.typedocPath;
 
     if (opts.python) {
       this.validations.add(NAME_PYTHON);
@@ -314,21 +317,19 @@ export class DocutilsValidator extends EventEmitter {
    * Validates that the correct version of `mkdocs` is installed
    */
   protected async validateMkDocs() {
-    let mkDocsPath: string | undefined;
-    try {
-      mkDocsPath = await whichMkDocs();
-    } catch {
-      // _pretty sure_ the exception code is always ENOENT
+    const pythonPath = this.pythonPath ?? (await findPython());
+
+    if (!pythonPath) {
       return this.fail(
-        `Could not find ${NAME_MKDOCS} executable in PATH. If it is installed, check your PATH environment variable.`
+        `Could not find ${NAME_PYTHON} executable in PATH. If it is installed, check your PATH environment variable.`
       );
     }
 
     let rawMkDocsVersion: string | undefined;
     try {
-      ({stdout: rawMkDocsVersion} = await exec(mkDocsPath, ['--version']));
+      ({stdout: rawMkDocsVersion} = await exec(pythonPath, ['-m', NAME_MKDOCS, '--version']));
     } catch (err) {
-      return this.fail(`${mkDocsPath} --version failed: ${err}`);
+      return this.fail(`Failed to get MkDocs version: ${err}`);
     }
     const match = rawMkDocsVersion.match(MKDOCS_VERSION_REGEX);
     if (match) {
@@ -343,12 +344,12 @@ export class DocutilsValidator extends EventEmitter {
       const {version: mkDocsReqdVersion} = mkDocsPipPkg;
       if (version !== mkDocsReqdVersion) {
         return this.fail(
-          `${NAME_MKDOCS} at ${mkDocsPath} is v${version}, but ${REQUIREMENTS_TXT_PATH} requires v${mkDocsReqdVersion}`
+          `${NAME_MKDOCS} is v${version}, but ${REQUIREMENTS_TXT_PATH} requires v${mkDocsReqdVersion}`
         );
       }
     } else {
       throw new DocutilsError(
-        `Could not parse version from "${mkDocsPath} --version". This is a bug. Output was ${rawMkDocsVersion}`
+        `Could not parse version from MkDocs. This is a bug. Output was ${rawMkDocsVersion}`
       );
     }
 
@@ -423,7 +424,7 @@ export class DocutilsValidator extends EventEmitter {
    */
   protected async validatePythonDeps() {
     let pipListOutput: string;
-    const pythonPath = this.pythonPath ?? (await whichPython());
+    const pythonPath = this.pythonPath ?? (await findPython());
     if (!pythonPath) {
       return this.fail(`Could not find ${NAME_PYTHON} in PATH. Is it installed?`);
     }
@@ -499,7 +500,7 @@ export class DocutilsValidator extends EventEmitter {
    * Asserts that the Python version is 3.x
    */
   protected async validatePythonVersion() {
-    const pythonPath = this.pythonPath ?? (await whichPython());
+    const pythonPath = this.pythonPath ?? (await findPython());
     if (!pythonPath) {
       return this.fail(`Could not find ${NAME_PYTHON} in PATH. Is it installed?`);
     }
@@ -520,17 +521,30 @@ export class DocutilsValidator extends EventEmitter {
   /**
    * Asserts TypeDoc is installed, runnable, the correct version, and that the config file is readable
    * and constaints required options
+   *
+   * @todo Another option would be to `npm exec typedoc@<version>` which delegates to `npx`.
    */
   protected async validateTypeDoc() {
     const pkgDir = await this.findPkgDir();
+    const typeDocPath = this.typeDocPath ?? (await findTypeDoc(pkgDir));
+
+    if (!typeDocPath) {
+      return this.fail(`Could not find ${NAME_TYPEDOC}; is it installed?`);
+    }
+    log.debug('Found %s at %s', NAME_TYPEDOC, typeDocPath);
+
     let rawTypeDocVersion: string;
     let typeDocVersion: string;
     try {
-      ({stdout: rawTypeDocVersion} = await exec('npm', ['exec', NAME_TYPEDOC, '--', '--version'], {
+      ({stdout: rawTypeDocVersion} = await exec(process.execPath, [typeDocPath, '--version'], {
         cwd: pkgDir,
       }));
-    } catch {
-      return this.fail(`Could not find ${NAME_TYPEDOC} executable from ${pkgDir}`);
+    } catch (err) {
+      return this.fail(
+        `Could not execute ${process.execPath} ${typeDocPath} from ${pkgDir}. Reason: ${
+          (err as Error).message
+        }`
+      );
     }
 
     if (rawTypeDocVersion) {
@@ -543,7 +557,8 @@ export class DocutilsValidator extends EventEmitter {
         );
       }
 
-      const reqdTypeDocVersion = DOCUTILS_PKG.dependencies!.typedoc!;
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const reqdTypeDocVersion = DOCUTILS_PKG.dependencies!.typedoc!; // this is our own package.json
       if (!satisfies(typeDocVersion, reqdTypeDocVersion)) {
         return this.fail(
           `Found TypeDoc version ${typeDocVersion}, but ${reqdTypeDocVersion} is required`
@@ -596,7 +611,7 @@ export class DocutilsValidator extends EventEmitter {
     if (!typeDocJson.out) {
       return this.fail(
         new DocutilsError(
-          `Missing "out" property in ${relTypeDocJsonPath}; path "${DEFAULT_REL_TYPEDOC_OUT_PATH} is recommended`
+          `Missing "out" property in ${relTypeDocJsonPath}; path "${DEFAULT_REL_TYPEDOC_OUT_PATH}" is recommended`
         )
       );
     }
@@ -714,6 +729,10 @@ export interface DocutilsValidatorOpts {
    * If `true`, run TypeDoc validation
    */
   typedoc?: boolean;
+  /**
+   * Path to `typedoc` executable
+   */
+  typedocPath?: string;
   /**
    * Path to `typedoc.json`
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/docutils",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Documentation generation utilities for Appium and related projects",
   "keywords": [
     "automation",
@@ -28,7 +28,7 @@
     "lib": "lib"
   },
   "bin": {
-    "appium-docs": "./build/lib/cli/index.js"
+    "appium-docs": "./bin/appium-docs.js"
   },
   "files": [
     "index.js",
@@ -49,10 +49,11 @@
     "start": "node ./build/lib/cli/index.js"
   },
   "dependencies": {
-    "@appium/support": "^4.0.0",
+    "@appium/support": "^4.0.1",
     "@appium/tsconfig": "^0.3.0",
     "@appium/typedoc-plugin-appium": "^0.6.4",
     "@sliphua/lilconfig-ts-loader": "3.2.2",
+    "@types/which": "3.0.0",
     "chalk": "4.1.2",
     "consola": "2.15.3",
     "diff": "5.1.0",
@@ -83,5 +84,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6b245534c213f3b8d6405515aee1e89133295098"
+  "gitHead": "2ca15818701b0af3c909dcc696dcd26ae6f50014"
 }