@appium/docutils 2.3.0 → 2.3.1

package/lib/cli/index.ts

@@ -23,6 +23,10 @@ const pkg = readPackageSync({cwd: fs.findRoot(__dirname)});
 const log = getLogger('cli');
 const IMPLICATIONS_FAILED_REGEX = /implications\s+failed:\n\s*(.+)\s->\s(.+)$/i;
 
+/**
+ * Entry point for the docutils CLI.
+ * @param argv Raw argv values (without node/bin by default).
+ */
 export async function main(argv = hideBin(process.argv)) {
   const config = await findConfig(argv);
 

package/lib/fs.ts

@@ -140,6 +140,8 @@ export const readJson = _.memoize(
     JSON.parse(await fs.readFile(filepath, 'utf8')),
 );
 
+type WhichFunction = (cmd: string, opts?: {nothrow: boolean}) => Promise<string | null>;
+
 /**
  * Writes contents to a file. Any JSON objects are stringified
  * @param filepath - Path to file
@@ -152,8 +154,6 @@ export function writeFileString(filepath: string, content: JsonValue) {
   });
 }
 
-type WhichFunction = (cmd: string, opts?: {nothrow: boolean}) => Promise<string | null>;
-
 /**
  * `which` with memoization
  */

package/lib/init.ts

@@ -83,6 +83,60 @@ export const initMkDocs: ScaffoldTask<InitMkDocsOptions, MkDocsYml> = createScaf
   },
 );
 
+/**
+ * Options for {@linkcode initMkDocs}
+ */
+export interface InitMkDocsOptions extends ScaffoldTaskOptions {
+  copyright?: string;
+  repoName?: string;
+  repoUrl?: string;
+  siteDescription?: string;
+  siteName?: string;
+}
+
+export interface InitPythonOptions extends ScaffoldTaskOptions {
+  /**
+   * Path to `python` (v3.x) executable
+   */
+  pythonPath?: string;
+
+  /**
+   * If true, upgrade only
+   */
+  upgrade?: boolean;
+}
+
+/**
+ * Options for `init` command handler
+ *
+ * The props of the various "path" options are rewritten as `dest` for the scaffold tasks functions.
+ */
+export type InitOptions = Simplify<
+  Omit<InitPythonOptions & InitMkDocsOptions, 'dest'> & {
+    /**
+     * If `true` will install Python deps
+     */
+    python?: boolean;
+    /**
+     * If `true` will initialize a `mkdocs.yml` file
+     */
+    mkdocs?: boolean;
+    /**
+     * Path to existing `package.json` file
+     */
+    packageJson?: string;
+    /**
+     * Path to new or existing `mkdocs.yml` file
+     */
+    mkdocsYml?: string;
+
+    /**
+     * If `true`, upgrade only
+     */
+    upgrade?: boolean;
+  }
+>;
+
 /**
  * Installs Python dependencies
  * @param opts Options
@@ -127,17 +181,6 @@ export async function initPython({
   log.success('Successfully installed Python dependencies');
 }
 
-/**
- * Options for {@linkcode initMkDocs}
- */
-export interface InitMkDocsOptions extends ScaffoldTaskOptions {
-  copyright?: string;
-  repoName?: string;
-  repoUrl?: string;
-  siteDescription?: string;
-  siteName?: string;
-}
-
 /**
  * Main handler for `init` command.
  *
@@ -177,46 +220,3 @@ export async function init({
     });
   }
 }
-
-export interface InitPythonOptions extends ScaffoldTaskOptions {
-  /**
-   * Path to `python` (v3.x) executable
-   */
-  pythonPath?: string;
-
-  /**
-   * If true, upgrade only
-   */
-  upgrade?: boolean;
-}
-
-/**
- * Options for `init` command handler
- *
- * The props of the various "path" options are rewritten as `dest` for the scaffold tasks functions.
- */
-export type InitOptions = Simplify<
-  Omit<InitPythonOptions & InitMkDocsOptions, 'dest'> & {
-    /**
-     * If `true` will install Python deps
-     */
-    python?: boolean;
-    /**
-     * If `true` will initialize a `mkdocs.yml` file
-     */
-    mkdocs?: boolean;
-    /**
-     * Path to existing `package.json` file
-     */
-    packageJson?: string;
-    /**
-     * Path to new or existing `mkdocs.yml` file
-     */
-    mkdocsYml?: string;
-
-    /**
-     * If `true`, upgrade only
-     */
-    upgrade?: boolean;
-  }
->;

package/lib/logger.ts

@@ -47,6 +47,11 @@ rootLogger.pauseLogs();
  */
 const loggers: Map<string, WeakRef<typeof ConsolaInstance>> = new Map();
 
+/**
+ * Returns a tagged logger, creating and caching one if needed.
+ * @param tag Logger tag.
+ * @param parent Parent logger to derive from.
+ */
 export function getLogger(tag: string, parent = rootLogger) {
   if (loggers.has(tag)) {
     const logger = loggers.get(tag)?.deref();

package/lib/scaffold.ts

@@ -18,26 +18,6 @@ import {NAME_ERR_ENOENT} from './constants';
 const log = getLogger('init');
 const dryRunLog = getLogger('dry-run', log);
 
-/**
- * Creates a unified patch for display in "dry run" mode
- * @param filename - File name to use
- * @param oldData - Old data
- * @param newData - New Data
- * @returns Patch string
- */
-function makePatch<T extends JsonValue>(
-  filename: string,
-  oldData: T | string,
-  newData: T | string,
-  serializer: ScaffoldTaskSerializer<T> = stringifyJson
-) {
-  return createPatch(
-    filename,
-    _.isString(oldData) ? oldData : serializer(oldData),
-    _.isString(newData) ? newData : serializer(newData)
-  );
-}
-
 /**
  * Options for a task which are not the {@link ScaffoldTaskOptions base options}
  */
@@ -55,6 +35,84 @@ export type ScaffoldTask<Opts extends ScaffoldTaskOptions, T extends JsonObject>
   opts: Opts
 ) => Promise<ScaffoldTaskResult<T>>;
 
+/**
+ * Optional function which can be used to post-process the content of a file. Usually used to merge
+ * various options with existing content
+ */
+export type ScaffoldTaskTransformer<Opts extends ScaffoldTaskOptions, T extends JsonValue> = (
+  content: Readonly<T>,
+  opts: TaskSpecificOpts<Opts>,
+  pkg: Readonly<NormalizedPackageJson>
+) => T;
+
+/**
+ * A function which deserializes a string into a JS value.
+ */
+export type ScaffoldTaskDeserializer<T> = (content: string) => T;
+
+/**
+ * A function which serializes a JS value into a string.
+ */
+export type ScaffoldTaskSerializer<T> = (content: T) => string;
+
+/**
+ * Options for {@linkcode createScaffoldTask}
+ */
+export interface CreateScaffoldTaskOptions<Opts extends ScaffoldTaskOptions, T extends JsonValue> {
+  /**
+   * Transformer function
+   */
+  transform?: ScaffoldTaskTransformer<Opts, T>;
+  /**
+   * Deserializer function
+   */
+  deserialize?: ScaffoldTaskDeserializer<T>;
+  /**
+   * Serializer function
+   */
+  serialize?: ScaffoldTaskSerializer<T>;
+}
+
+/**
+ * Base options for all scaffold tasks
+ */
+export interface ScaffoldTaskOptions {
+  /**
+   * Current working directory
+   */
+  cwd?: string;
+  /**
+   * Destination file
+   */
+  dest?: string;
+  /**
+   * If `true` will not write files
+   */
+  dryRun?: boolean;
+  /**
+   * If `true` will overwrite fields in `typedoc.json`
+   */
+  overwrite?: boolean;
+  /**
+   * Path to `package.json`
+   */
+  packageJson?: string;
+}
+
+/**
+ * The return value of a {@linkcode ScaffoldTask}
+ */
+export interface ScaffoldTaskResult<T> {
+  /**
+   * The content of whatever it wrote or would write
+   */
+  content: T;
+  /**
+   * The filepath of whatever it wrote or would write
+   */
+  path: string;
+}
+
 /**
  * Factory for a {@linkcode ScaffoldTask}.
  *
@@ -153,79 +211,21 @@ export function createScaffoldTask<Opts extends ScaffoldTaskOptions, T extends J
 }
 
 /**
- * Optional function which can be used to post-process the content of a file. Usually used to merge
- * various options with existing content
- */
-export type ScaffoldTaskTransformer<Opts extends ScaffoldTaskOptions, T extends JsonValue> = (
-  content: Readonly<T>,
-  opts: TaskSpecificOpts<Opts>,
-  pkg: Readonly<NormalizedPackageJson>
-) => T;
-
-/**
- * A function which deserializes a string into a JS value.
- */
-export type ScaffoldTaskDeserializer<T> = (content: string) => T;
-
-/**
- * A function which serializes a JS value into a string.
- */
-export type ScaffoldTaskSerializer<T> = (content: T) => string;
-
-/**
- * Options for {@linkcode createScaffoldTask}
- */
-export interface CreateScaffoldTaskOptions<Opts extends ScaffoldTaskOptions, T extends JsonValue> {
-  /**
-   * Transformer function
-   */
-  transform?: ScaffoldTaskTransformer<Opts, T>;
-  /**
-   * Deserializer function
-   */
-  deserialize?: ScaffoldTaskDeserializer<T>;
-  /**
-   * Serializer function
-   */
-  serialize?: ScaffoldTaskSerializer<T>;
-}
-
-/**
- * Base options for all scaffold tasks
- */
-export interface ScaffoldTaskOptions {
-  /**
-   * Current working directory
-   */
-  cwd?: string;
-  /**
-   * Destination file
-   */
-  dest?: string;
-  /**
-   * If `true` will not write files
-   */
-  dryRun?: boolean;
-  /**
-   * If `true` will overwrite fields in `typedoc.json`
-   */
-  overwrite?: boolean;
-  /**
-   * Path to `package.json`
-   */
-  packageJson?: string;
-}
-
-/**
- * The return value of a {@linkcode ScaffoldTask}
+ * Creates a unified patch for display in "dry run" mode
+ * @param filename - File name to use
+ * @param oldData - Old data
+ * @param newData - New Data
+ * @returns Patch string
  */
-export interface ScaffoldTaskResult<T> {
-  /**
-   * The content of whatever it wrote or would write
-   */
-  content: T;
-  /**
-   * The filepath of whatever it wrote or would write
-   */
-  path: string;
+function makePatch<T extends JsonValue>(
+  filename: string,
+  oldData: T | string,
+  newData: T | string,
+  serializer: ScaffoldTaskSerializer<T> = stringifyJson
+) {
+  return createPatch(
+    filename,
+    _.isString(oldData) ? oldData : serializer(oldData),
+    _.isString(newData) ? newData : serializer(newData)
+  );
 }

package/lib/util.ts

@@ -73,6 +73,8 @@ export const argify: (obj: Record<string, string | number | boolean | undefined>
     _.flatten
   );
 
+export type SpawnBackgroundProcessOpts = Omit<SpawnOptions, 'stdio'>;
+
 /**
  * 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.
@@ -97,8 +99,6 @@ export async function spawnBackgroundProcess(command: string, args: string[], op
   });
 }
 
-export type SpawnBackgroundProcessOpts = Omit<SpawnOptions, 'stdio'>;
-
 /**
  * Wraps {@linkcode exec} with error handling that appends stderr to the thrown error message.
  */

package/lib/validate.ts

@@ -41,6 +41,29 @@ const log = getLogger('validate');
  */
 export type ValidationKind = typeof NAME_PYTHON | typeof NAME_MKDOCS;
 
+export interface DocutilsValidatorOpts {
+  /**
+   * Current working directory
+   */
+  cwd?: string;
+  /**
+   * Path to `mkdocs.yml`
+   */
+  mkdocsYml?: string;
+  /**
+   * If `true`, run Python validation
+   */
+  python?: boolean;
+  /**
+   * Path to `python` executable
+   */
+  pythonPath?: string;
+  /**
+   * If `true`, run MkDocs validation
+   */
+  mkdocs?: boolean;
+}
+
 /**
  * This class is designed to run _all_ validation checks (as requested by the user), and emit events for
  * each failure encountered.
@@ -51,6 +74,30 @@ export type ValidationKind = typeof NAME_PYTHON | typeof NAME_MKDOCS;
  * @todo Use [`strict-event-emitter-types`](https://npm.im/strict-event-emitter-types)
  */
 export class DocutilsValidator extends EventEmitter {
+  /**
+   * Emitted when validation begins with a list of validation kinds to be performed
+   * @event
+   */
+  public static readonly BEGIN = 'begin';
+
+  /**
+   * Emitted when validation ends with an error count
+   * @event
+   */
+  public static readonly END = 'end';
+
+  /**
+   * Emitted when a validation fails, with the associated {@linkcode DocutilsError}
+   * @event
+   */
+  public static readonly FAILURE = 'fail';
+
+  /**
+   * Emitted when a validation succeeds
+   * @event
+   */
+  public static readonly SUCCESS = 'ok';
+
   /**
    * Current working directory. Defaults to `process.cwd()`
    * @todo This cannot yet be overridden by user
@@ -82,30 +129,6 @@ export class DocutilsValidator extends EventEmitter {
    */
   protected mkDocsYmlPath?: string;
 
-  /**
-   * Emitted when validation begins with a list of validation kinds to be performed
-   * @event
-   */
-  public static readonly BEGIN = 'begin';
-
-  /**
-   * Emitted when validation ends with an error count
-   * @event
-   */
-  public static readonly END = 'end';
-
-  /**
-   * Emitted when a validation fails, with the associated {@linkcode DocutilsError}
-   * @event
-   */
-  public static readonly FAILURE = 'fail';
-
-  /**
-   * Emitted when a validation succeeds
-   * @event
-   */
-  public static readonly SUCCESS = 'ok';
-
   private requirementsTxt: PipPackage[] | undefined;
 
   /**
@@ -392,30 +415,3 @@ export class DocutilsValidator extends EventEmitter {
     this.ok('Python version OK');
   }
 }
-
-/**
- * Options for {@linkcode DocutilsValidator} constructor
- */
-
-export interface DocutilsValidatorOpts {
-  /**
-   * Current working directory
-   */
-  cwd?: string;
-  /**
-   * Path to `mkdocs.yml`
-   */
-  mkdocsYml?: string;
-  /**
-   * If `true`, run Python validation
-   */
-  python?: boolean;
-  /**
-   * Path to `python` executable
-   */
-  pythonPath?: string;
-  /**
-   * If `true`, run MkDocs validation
-   */
-  mkdocs?: boolean;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/docutils",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Documentation generation utilities for Appium and related projects",
   "keywords": [
     "automation",
@@ -46,15 +46,15 @@
     "start": "node ./build/lib/cli/index.js"
   },
   "dependencies": {
-    "@appium/support": "7.1.0",
+    "@appium/support": "7.1.1",
     "consola": "3.4.2",
-    "diff": "8.0.4",
+    "diff": "9.0.0",
     "lilconfig": "3.1.3",
     "lodash": "4.18.1",
     "package-directory": "8.2.0",
     "read-pkg": "10.1.0",
-    "teen_process": "4.1.0",
-    "type-fest": "5.5.0",
+    "teen_process": "4.1.1",
+    "type-fest": "5.6.0",
     "yaml": "2.8.3",
     "yargs": "18.0.0",
     "yargs-parser": "22.0.0"
@@ -66,5 +66,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7a8965f5c30ffec2ad04ce75903b3960537cef06"
+  "gitHead": "17f84265d10944fec06ae7684ae8ad77d1224b50"
 }

package/requirements.txt

@@ -2,4 +2,4 @@ mkdocs==1.6.1
 mkdocs-git-revision-date-localized-plugin==1.5.1
 mkdocs-material==9.7.6
 mkdocs-redirects==1.2.3
-mike==2.1.4
+mike==2.2.0