@appium/docutils 0.1.6 → 0.2.1

package/lib/logger.ts

@@ -0,0 +1,198 @@
+/**
+ * It's a logger.
+ *
+ * Since this is a CLI app only, it doesn't necessarily make sense to consume `@appium/support`'s logger.
+ *
+ * @module
+ */
+
+import figures from 'figures';
+import logSymbols from 'log-symbols';
+import chalk, {ForegroundColor, BackgroundColor} from 'chalk';
+import consola, {
+  logType as LogType,
+  ConsolaReporterLogObject,
+  FancyReporter,
+  FancyReporterOptions,
+  Consola,
+  ConsolaOptions,
+  LogLevel,
+} from 'consola';
+import {DEFAULT_LOG_LEVEL, LogLevelMap} from './constants';
+import _ from 'lodash';
+
+/**
+ * This is a reporter for `consola` which uses some extra/custom icons and colors.
+ *
+ * @privateRemarks
+ * I did not like that the default `FancyReport` logs errors in _green_ without any sort of icon.
+ * Both `log-symbols` and `consola` consume `chalk`, so we do too. `consola` also depends on `figures`.
+ */
+class DocutilsReporter extends FancyReporter {
+  /**
+   * Mapping of log types (the name of the logging method called) to chalk fg colors
+   */
+  static TYPE_COLOR_MAP = {
+    info: 'cyan',
+    success: 'green',
+    error: 'red',
+    warn: 'yellow',
+  } as const;
+
+  /**
+   * Mapping of log levels to chalk fg colors
+   */
+  static LEVEL_COLORS = {
+    0: 'red',
+    1: 'yellow',
+    2: 'white',
+    3: 'green',
+  } as const;
+
+  /**
+   * Mapping of log types to icons/symbols
+   */
+  static TYPE_ICONS = {
+    info: logSymbols.info,
+    success: logSymbols.success,
+    error: logSymbols.error,
+    warn: logSymbols.warning,
+    debug: figures('›'),
+    trace: figures('›'),
+  } as const;
+
+  /**
+   * Default color to use if we can't find a color for the log type or level
+   */
+  static readonly DEFAULT_COLOR = 'grey';
+
+  /**
+   * Type guard to check if a log type has a color
+   * @param type A log type
+   */
+  static hasTypeColor(type: LogType): type is keyof typeof DocutilsReporter.TYPE_COLOR_MAP {
+    return type in DocutilsReporter.TYPE_COLOR_MAP;
+  }
+
+  /**
+   * Type guard to check if a log level has a color
+   * @param level A log level
+   */
+  static hasLevelColor(level: LogLevel): level is keyof typeof DocutilsReporter.LEVEL_COLORS {
+    return level in DocutilsReporter.LEVEL_COLORS;
+  }
+
+  /**
+   * Type guard to check if a log type has an icon
+   * @param type A log type
+   */
+  static hasTypeIcon(type: LogType): type is keyof typeof DocutilsReporter.TYPE_ICONS {
+    return type in DocutilsReporter.TYPE_ICONS;
+  }
+
+  /**
+   * Prefixes the logging output with colors and symbols, depending on contents of `logObj`.
+   * @param logObj Consola's log object
+   * @param isBadge {@linkcode FancyReporter} uses this; I think it depends on the terminal width
+   * @returns
+   */
+  protected override formatType(logObj: ConsolaReporterLogObject, isBadge?: boolean): string {
+    const {
+      TYPE_COLOR_MAP,
+      LEVEL_COLORS,
+      TYPE_ICONS,
+      hasTypeColor,
+      hasLevelColor,
+      hasTypeIcon,
+      DEFAULT_COLOR,
+    } = DocutilsReporter;
+
+    let typeColor: typeof ForegroundColor;
+    if (hasTypeColor(logObj.type)) {
+      typeColor = TYPE_COLOR_MAP[logObj.type];
+    } else if (hasLevelColor(logObj.level)) {
+      typeColor = LEVEL_COLORS[logObj.level];
+    } else {
+      typeColor = <typeof ForegroundColor>(
+        ((this.options as FancyReporterOptions).secondaryColor ?? DEFAULT_COLOR)
+      );
+    }
+
+    if (isBadge) {
+      return chalk[('bg' + _.capitalize(typeColor)) as typeof BackgroundColor].black(
+        ` ${_.toUpper(logObj.type)}`
+      );
+    }
+
+    const type = hasTypeIcon(logObj.type) ? TYPE_ICONS[logObj.type] : logObj.type;
+    return type ? chalk[typeColor](type) : '';
+  }
+}
+
+/**
+ * The global log level
+ *
+ * "Global" inasmuch as any logger created from the root logger will use this level.
+ */
+let globalLevel = LogLevelMap[DEFAULT_LOG_LEVEL];
+
+/**
+ * The logger from which all loggers are created.  This one uses a unique tag and our custom reporter.
+ */
+const rootLogger = createLogProxy(
+  consola.create({defaults: {tag: 'docutils'}, reporters: [new DocutilsReporter()]})
+);
+
+/**
+ * @summary Creates a log-level-propagating proxy for a {@linkcode Consola} logger.
+ * @description
+ * Alright.  So when you create a new logger via {@linkcode Consola.create}, it's basically a clone
+ * of its parent with a new set of options.
+ *
+ * If we change the log level of the root logger (which we do: see `cli/index.ts`), we may (almost
+ * certainly) have
+ * child loggers which: a) have already been created and b) have inherited the old/default log level
+ * from the root logger. We don't _want_ that (though this is likely a reasonable use case) for our
+ * purposes.
+ *
+ * The implementation below solves the problem by maintaining its own singleton log level value, and
+ * intercepts the `level` property of any logger created from the root logger.
+ *
+ * There are other ways to go about this which may be better, but this seemed pretty straightforward.
+ */
+function createLogProxy(logger: Consola): Consola {
+  return new Proxy(logger, {
+    get(target, prop, receiver) {
+      if (prop === 'level') {
+        return globalLevel;
+      }
+      if (prop === 'create') {
+        const create = Reflect.get(target, prop, receiver) as Consola['create'];
+        return (opts: ConsolaOptions) => createLogProxy(create.call(receiver, opts));
+      }
+      if (prop === '_defaults') {
+        const defaults = Reflect.get(target, prop, receiver);
+        return {...defaults, level: globalLevel};
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+    set(target, prop, value, receiver) {
+      if (prop === 'level') {
+        globalLevel = value as LogLevel;
+        return true;
+      }
+      return Reflect.set(target, prop, value, receiver);
+    },
+  });
+}
+
+/**
+ * The proxied root logger
+ * @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,10 +1,14 @@
 import {exec} from 'teen_process';
+// eslint-disable-next-line import/no-unresolved
 import log from './logger';
 
 const DEFAULT_REMOTE = 'origin';
 const DEFAULT_BRANCH = 'gh-pages';
 const MIKE_VER_STRING = 'mike 1.';
 
+/**
+ * @deprecated Use the `deploy` export from `@appium/docutils`
+ */
 export class Mike {
   /** @type {string} */ remote;
   /** @type {string} */ branch;

package/lib/model.ts

@@ -0,0 +1,92 @@
+/**
+ * Various data models, mostly referring to config files
+ *
+ * @module
+ */
+
+import type {Jsonify, JsonValue, TsConfigJson as TsConfigJsonBase} from 'type-fest';
+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;
+  }
+>;
+
+/**
+ * A `typedoc.json` file w/ `$schema` and `extends` props
+ *
+ * TypeDoc doesn't recognize `$schema` and ignores it; its own config parser expands the value of
+ * `extends` before it reaches its `Options` class. This is why we cannot use `TypeDocOptions` directly.
+ */
+export type TypeDocJson = Jsonify<
+  Partial<TypeDocOptions> & {
+    $schema?: string;
+    extends?: string;
+  }
+>;
+
+/**
+ * The `nav` prop of an `mkdocs.yml` file
+ * @see {@linkcode MkDocsYml}
+ */
+export type MkDocsYmlNav = Array<string | Record<string, string> | Record<string, MkDocsYmlNav>>;
+
+/**
+ * This was built by hand from the MkDocs documentation
+ * @see https://www.mkdocs.org/user-guide/configuration/
+ */
+export type MkDocsYml = Jsonify<{
+  copyright?: string;
+  dev_addr?: string;
+  docs_dir?: string;
+  extra_css?: string[];
+  extra_javascript?: string[];
+  extra_templates?: string[];
+  extra?: Record<string, JsonValue>;
+  hooks?: string[];
+  INHERIT?: string;
+  markdown_extensions?: Array<string | Record<string, JsonValue>>;
+  nav?: MkDocsYmlNav;
+  plugins?: Array<string | Record<string, JsonValue>>;
+  repo_name?: string;
+  repo_url?: string;
+  site_dir?: string;
+  /**
+   * This is _actually_ required by mkdocs
+   */
+  site_name?: string;
+  site_description?: string;
+  strict?: boolean;
+  theme?: MkDocsYmlTheme;
+  use_directory_urls?: boolean;
+  watch?: string[];
+}>;
+
+/**
+ * The `theme` prop of an `mkdocs.yml`
+ * @see {@linkcode MkDocsYml}
+ */
+export type MkDocsYmlTheme =
+  | string
+  | ({
+      name: string;
+      locale?: string;
+      custom_dir?: string;
+      static_templates?: string[];
+    } & Record<string, JsonValue>);
+
+/**
+ * The data parsed from a `requirements.txt` file, or the output of `pip list --json`
+ */
+export interface PipPackage {
+  name: string;
+  version: string;
+}

package/lib/scaffold.ts

@@ -0,0 +1,225 @@
+/**
+ * Implementation of a generic "create and/or update some file" task
+ * @module
+ */
+
+import {fs} from '@appium/support';
+import logger from './logger';
+import path from 'node:path';
+import {createPatch} from 'diff';
+import {NormalizedPackageJson} from 'read-pkg';
+import {JsonValue, JsonObject} from 'type-fest';
+import {DocutilsError} from './error';
+import {relative} from './util';
+import _ from 'lodash';
+import {stringifyJson, readPackageJson, safeWriteFile} from './fs';
+import {NAME_ERR_ENOENT, NAME_ERR_EEXIST} from './constants';
+
+const log = logger.withTag('init');
+const dryRunLog = log.withTag('dry-run');
+
+/**
+ * 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}
+ */
+export type TaskSpecificOpts<Opts extends ScaffoldTaskOptions> = Omit<
+  Opts,
+  keyof ScaffoldTaskOptions
+>;
+
+/**
+ * A function which performs some scaffolding task.
+ *
+ * @see {@linkcode createScaffoldTask}
+ */
+export type ScaffoldTask<Opts extends ScaffoldTaskOptions, T extends JsonObject> = (
+  opts: Opts
+) => Promise<ScaffoldTaskResult<T>>;
+
+/**
+ * Factory for a {@linkcode ScaffoldTask}.
+ *
+ * @param defaultFilename Default file to create
+ * @param defaultContent Default content to use
+ * @param description Description of task
+ * @param opts Options
+ * @returns A scaffold task
+ */
+export function createScaffoldTask<Opts extends ScaffoldTaskOptions, T extends JsonObject>(
+  defaultFilename: string,
+  defaultContent: T,
+  description: string,
+  {
+    transform = _.identity,
+    deserialize = JSON.parse,
+    serialize = stringifyJson,
+  }: CreateScaffoldTaskOptions<Opts, T> = {}
+): ScaffoldTask<Opts, T> {
+  return async ({
+    overwrite = false,
+    cwd = process.cwd(),
+    packageJson: packageJsonPath,
+    dest,
+    dryRun = false,
+    ...opts
+  }: Opts): Promise<ScaffoldTaskResult<T>> => {
+    const relativePath = relative(cwd);
+    const {pkgPath, pkg} = await readPackageJson(
+      packageJsonPath ? path.dirname(packageJsonPath) : cwd,
+      true
+    );
+    const pkgDir = path.dirname(pkgPath);
+    dest = dest ?? path.join(pkgDir, defaultFilename);
+    const relativeDest = relativePath(dest);
+    log.debug('Initializing %s', relativeDest);
+    let shouldWriteDest = false;
+    let destContent: T;
+    let result: ScaffoldTaskResult<T>;
+    try {
+      destContent = deserialize(await fs.readFile(dest, 'utf8'));
+      log.debug('Found existing file %s', relativeDest);
+    } catch (e) {
+      const err = e as NodeJS.ErrnoException;
+      if (err.code !== NAME_ERR_ENOENT) {
+        throw err;
+      }
+      shouldWriteDest = true;
+      log.debug('Creating new file %s', relativeDest);
+      destContent = {} as T;
+    }
+
+    const defaults: T = transform(defaultContent, opts, pkg);
+    const finalDestContent: T = _.defaultsDeep({}, destContent, defaults);
+
+    shouldWriteDest = shouldWriteDest || !_.isEqual(destContent, finalDestContent);
+
+    if (shouldWriteDest) {
+      log.info('Changes needed to %s', relativeDest);
+      log.debug('Original %s: %O', relativeDest, destContent);
+      log.debug('Final %s: %O', relativeDest, finalDestContent);
+      const patch = makePatch(dest, destContent, finalDestContent, serialize);
+
+      if (dryRun) {
+        dryRunLog.info('Would apply the following patch: \n\n%s', patch);
+        result = {path: dest, content: finalDestContent};
+        return result;
+      }
+
+      try {
+        await safeWriteFile(dest, finalDestContent, overwrite);
+      } catch (e) {
+        const err = e as NodeJS.ErrnoException;
+        // this should only be thrown if `force` is false
+        if (err.code === NAME_ERR_EEXIST) {
+          log.info(`${relativeDest} already exists; continuing...`);
+          log.debug(`Tried to apply patch:\n\n${patch}`);
+        } else {
+          throw new DocutilsError(`Could not write to ${relativeDest}. Reason: ${err.message}`, {
+            cause: err,
+          });
+        }
+      }
+    } else {
+      log.info('No changes to %s', relativeDest);
+    }
+    log.success('Initialized %s', description);
+    return {path: dest, content: finalDestContent};
+  };
+}
+
+/**
+ * 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: 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;
+}

package/lib/util.ts

@@ -0,0 +1,76 @@
+/**
+ * Utilities
+ * @module
+ */
+
+import _ from 'lodash';
+import path from 'node:path';
+import type {SubProcess} from 'teen_process';
+
+/**
+ * Computes a relative path, prepending `./`
+ */
+export const relative = _.curry(
+  (from: string, to: string): string => `.${path.sep}${path.relative(from, to)}`
+);
+
+/**
+ * A stopwatch-like thing
+ *
+ * Used for displaying elapsed time in milliseconds
+ * @param id - Unique identifier
+ * @returns Function that returns the elapsed time in milliseconds
+ */
+export function stopwatch(id: string) {
+  const start = Date.now();
+  stopwatch.cache.set(id, start);
+  return () => {
+    const result = Date.now() - stopwatch.cache.get(id)!;
+    stopwatch.cache.delete(id);
+    return result;
+  };
+}
+stopwatch.cache = new Map<string, number>();
+
+export type TupleToObject<
+  T extends readonly any[],
+  M extends Record<Exclude<keyof T, keyof any[]>, PropertyKey>
+> = {[K in Exclude<keyof T, keyof any[]> as M[K]]: T[K]};
+
+/**
+ * Type guard to narrow an array to a string array
+ * @param value any value
+ * @returns `true` if the array is `string[]`
+ */
+export const isStringArray = _.overEvery(_.isArray, _.partial(_.every, _, _.isString)) as (
+  value: any
+) => value is string[];
+
+/**
+ * Converts an object of string values to an array of arguments for CLI
+ *
+ * Supports `boolean` and `number` values as well.  `boolean`s are assumed to be flags which default
+ * to `false`, so they will only be added to the array if the value is `true`.
+ */
+export const argify: (obj: Record<string, string | number | boolean | undefined>) => string[] =
+  _.flow(
+    _.entries,
+    _.flatten,
+    (list) =>
+      list.map((value, idx) => {
+        if (value === true) {
+          return `--${value}`;
+        } else if (value === false || value === undefined) {
+          return;
+        }
+        return idx % 2 === 0 ? `--${value}` : value;
+      }),
+    _.compact
+  );
+
+/**
+ * Conversion of the parameters of {@linkcode Subprocess.start} to an object.
+ */
+export type TeenProcessSubprocessStartOpts = Partial<
+  TupleToObject<Parameters<SubProcess['start']>, ['startDetector', 'detach', 'timeoutMs']>
+>;