@appium/docutils 0.1.6 → 0.2.1

package/build/lib/validation/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../lib/validation/validator.ts"],"names":[],"mappings":"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"}

package/lib/builder/deploy.ts

@@ -0,0 +1,223 @@
+/**
+ * Functions for running `mike`
+ *
+ * @module
+ */
+
+import _ from 'lodash';
+import {exec, SubProcess, TeenProcessExecOptions} from 'teen_process';
+import path from 'node:path';
+import {
+  DEFAULT_DEPLOY_BRANCH,
+  DEFAULT_DEPLOY_REMOTE,
+  DEFAULT_SERVE_HOST,
+  DEFAULT_SERVE_PORT,
+  NAME_BIN,
+  NAME_MKDOCS_YML,
+} from '../constants';
+import {DocutilsError} from '../error';
+import {findMkDocsYml, readPackageJson, whichMike} from '../fs';
+import logger from '../logger';
+import {argify, stopwatch, TeenProcessSubprocessStartOpts} from '../util';
+
+const log = logger.withTag('builder:deploy');
+
+/**
+ * Runs `mike serve`
+ * @param args Extra args to `mike build`
+ * @param opts Extra options for `teen_process.Subprocess.start`
+ * @param mikePath Path to `mike` executable
+ */
+async function doServe(
+  args: string[] = [],
+  {startDetector, detach, timeoutMs}: TeenProcessSubprocessStartOpts = {},
+  mikePath?: string
+) {
+  mikePath = mikePath ?? (await whichMike());
+  const finalArgs = ['serve', ...args];
+  log.debug('Launching %s with args: %O', mikePath, finalArgs);
+  const proc = new SubProcess(mikePath, finalArgs);
+  return await proc.start(startDetector, detach, timeoutMs);
+}
+
+/**
+ * Runs `mike build`
+ * @param args Extra args to `mike build`
+ * @param opts Extra options to `teen_process.exec`
+ * @param mikePath Path to `mike` executable
+ */
+async function doDeploy(args: string[] = [], opts: TeenProcessExecOptions = {}, mikePath?: string) {
+  mikePath = mikePath ?? (await whichMike());
+  const finalArgs = ['deploy', ...args];
+  log.debug('Launching %s with args: %O', mikePath, finalArgs);
+  return await exec(mikePath, finalArgs, opts);
+}
+
+/**
+ * Derives a deployment version from `package.json`
+ * @param packageJsonPath Path to `package.json` if known
+ * @param cwd Current working directory
+ */
+async function findDeployVersion(packageJsonPath?: string, cwd = process.cwd()): Promise<string> {
+  const {pkg} = await readPackageJson(packageJsonPath ? path.dirname(packageJsonPath) : cwd, true);
+  const version = pkg.version;
+  if (!version) {
+    throw new DocutilsError(
+      'No "version" field found in package.json; please add one or specify a version to deploy'
+    );
+  }
+  return version;
+}
+
+/**
+ * Runs `mike build` or `mike serve`
+ * @param opts Options
+ */
+export async function deploy({
+  mkdocsYml: mkDocsYmlPath,
+  packageJson: packageJsonPath,
+  deployVersion: version,
+  cwd = process.cwd(),
+  serve = false,
+  push = false,
+  branch = DEFAULT_DEPLOY_BRANCH,
+  remote = DEFAULT_DEPLOY_REMOTE,
+  prefix,
+  message,
+  alias,
+  rebase = true,
+  port = DEFAULT_SERVE_PORT,
+  host = DEFAULT_SERVE_HOST,
+  serveOpts,
+  execOpts,
+}: DeployOpts = {}) {
+  const stop = stopwatch('deploy');
+  mkDocsYmlPath = mkDocsYmlPath ?? (await findMkDocsYml(cwd));
+  if (!mkDocsYmlPath) {
+    throw new DocutilsError(
+      `Could not find ${NAME_MKDOCS_YML} from ${cwd}; run "${NAME_BIN} init" to create it`
+    );
+  }
+  version = version ?? (await findDeployVersion(packageJsonPath, cwd));
+  const mikeOpts = {
+    'config-file': mkDocsYmlPath,
+    push,
+    remote,
+    branch,
+    prefix,
+    message,
+    rebase,
+    port,
+    host,
+  };
+  if (serve) {
+    const mikeArgs = [
+      ...argify(_.pickBy(mikeOpts, (value) => _.isNumber(value) || Boolean(value))),
+      version,
+    ];
+    if (alias) {
+      mikeArgs.push(alias);
+    }
+    // unsure about how SIGHUP is handled here
+    await doServe(mikeArgs, serveOpts);
+  } else {
+    const mikeArgs = [
+      ...argify(
+        _.omitBy(
+          mikeOpts,
+          (value, key) => _.includes(['port', 'host'], key) || (!_.isNumber(value) && !value)
+        )
+      ),
+      version,
+    ];
+    if (alias) {
+      mikeArgs.push(alias);
+    }
+    await doDeploy(mikeArgs, execOpts);
+
+    log.success('Mike finished deployment into branch %s (%dms)', branch, stop());
+  }
+}
+
+/**
+ * Options for {@linkcode deploy}.
+ */
+export interface DeployOpts {
+  /**
+   * Path to `mike.yml`
+   */
+  mkdocsYml?: string;
+
+  /**
+   * Current working directory
+   * @defaultValue `process.cwd()`
+   */
+  cwd?: string;
+
+  /**
+   * Path to `package.json`
+   *
+   * Used to find `mike.yml` if unspecified.
+   */
+  packageJson?: string;
+
+  /**
+   * If `true`, run `mike serve` instead of `mike build`
+   */
+  serve?: boolean;
+
+  /**
+   * If `true`, push `branch` to `remote`
+   */
+  push?: boolean;
+  /**
+   * Branch to commit to
+   * @defaultValue gh-pages
+   */
+  branch?: string;
+  /**
+   * Remote to push to
+   * @defaultValue origin
+   */
+  remote?: string;
+  /**
+   * Subdirectory within `branch` to deploy to
+   */
+  prefix?: string;
+  /**
+   * Commit message
+   */
+  message?: string;
+  /**
+   * Version (dir) to deploy build to
+   */
+  deployVersion?: string;
+  /**
+   * Alias for the build (e.g., `latest`); triggers alias update
+   */
+  alias?: string;
+  /**
+   * If `true`, rebase `branch` before pushing
+   */
+  rebase?: boolean;
+  /**
+   * Port to serve on
+   * @defaultValue 8000
+   */
+  port?: number;
+  /**
+   * Host to serve on
+   * @defaultValue localhost
+   */
+  host?: string;
+
+  /**
+   * Extra options for {@linkcode teen_process.exec}
+   */
+  execOpts?: TeenProcessExecOptions;
+
+  /**
+   * Extra options for {@linkcode teen_process.Subprocess.start}
+   */
+  serveOpts?: TeenProcessSubprocessStartOpts;
+}

package/lib/builder/index.ts

@@ -0,0 +1,4 @@
+export * from './deploy';
+export * from './site';
+export * from './reference';
+export * from './nav';

package/lib/builder/nav.ts

@@ -0,0 +1,399 @@
+/**
+ * Handles updating/adding the `nav` property of `mkdocs.yml`, based on the output of `typedoc`;
+ * specifically, the command documentation generated by `@appium/typedoc-plugin-appium`.
+ *
+ * @module
+ */
+
+import {fs} from '@appium/support';
+import _ from 'lodash';
+import path from 'node:path';
+import {
+  DEFAULT_NAV_HEADER,
+  DEFAULT_REL_TYPEDOC_OUT_PATH,
+  NAME_BIN,
+  NAME_MKDOCS_YML,
+  NAME_TYPEDOC_JSON,
+} from '../constants';
+import {DocutilsError} from '../error';
+import {
+  findDirsIn,
+  findMkDocsYml,
+  findTypeDocJsonPath,
+  readTypedocJson,
+  readYaml,
+  safeWriteFile,
+  stringifyYaml,
+} from '../fs';
+import logger from '../logger';
+import {MkDocsYml, MkDocsYmlNav} from '../model';
+import {relative} from '../util';
+
+const log = logger.withTag('builder:nav');
+
+/**
+ * Gets a list of `.md` files relative to `docs_dir`
+ * @param targetDir Directory ostensibly containing Markdown files; must be absolute
+ * @param mkDocsDocsDir The path to the `docs_dir` in the `mkdocs.yml` file; must be absolute
+ * @returns List of Markdown files relative to the `docs_dir` in the `mkdocs.yml` file
+ */
+async function findRelativeMarkdownFiles(
+  targetDir: string,
+  mkDocsDocsDir: string
+): Promise<string[]> {
+  if (!path.isAbsolute(targetDir)) {
+    throw new DocutilsError(`Expected absolute path, got '${targetDir}'`);
+  }
+  if (!path.isAbsolute(mkDocsDocsDir)) {
+    throw new DocutilsError(`Expected absolute path, got '${mkDocsDocsDir}'`);
+  }
+  const relDir = path.relative(mkDocsDocsDir, targetDir);
+  const dirEnts = await fs.readdir(targetDir, {withFileTypes: true});
+  return dirEnts
+    .filter((ent) => ent.isFile() && ent.name.endsWith('.md'))
+    .map((ent) => path.join(relDir, ent.name));
+}
+
+/**
+ * Because the `nav` property of `mkdocs.yml` is both a recursive type and a kind of awful one, it's
+ * easier to work with it if we rewrite the data into a flat array of objects. We keep a `keypath`
+ * prop which represents the deep/nested location within the `nav` object.
+ *
+ * @privateRemarks This function is not recursive; instead it loops over a queue of items to process
+ * data, and we append to that queue while processing if needed.
+ * @param nav Contents of the `nav` prop of `mkdocs.yml`
+ * @returns A list of objects, each with a `keypath` property and a `fileOrUrl` property (and maybe
+ * a `name` property)
+ */
+export function parseNav(nav: MkDocsYmlNav): ParsedNavData[] {
+  let parsedNav: ParsedNavData[] = [];
+  const entries = Object.entries(nav);
+  type QueueItem = {
+    entries: typeof entries;
+    keypath: string;
+  };
+  const queue: QueueItem[] = [{entries, keypath: ''}];
+
+  while (queue.length) {
+    const {entries, keypath} = queue.shift()!;
+    for (const [key, item] of entries) {
+      if (_.isString(item)) {
+        const navData: ParsedNavData = {
+          keypath: keypath ? `${keypath}.${key}` : key,
+          fileOrUrl: item,
+        };
+
+        // if the key is not convertible to a number, it's a name
+        // which was manually put there by somebody.
+        if (Number.isNaN(Number(key))) {
+          navData.name = key;
+        }
+        parsedNav = [...parsedNav, navData];
+      } else if (_.isObject(item)) {
+        const subEntries = Object.entries(item);
+        queue.push({entries: subEntries, keypath: keypath ? `${keypath}.${key}` : key});
+      }
+    }
+  }
+  return parsedNav;
+}
+
+/**
+ * Finds all items within the list of parsed nav data which correpsond to the header.  This is
+ * imperfect, as it's possible for the header string to appear in multiple places in the nav, but let's just ignore that until we can't.
+ * @param navData Some parsed nav data
+ * @param header Header name
+ */
+function filterHeaderItems(navData: ParsedNavData[], header: string) {
+  return _.filter(navData, (item) => _.toPath(item.keypath).includes(header));
+}
+
+/**
+ *
+ * @param rootHeaderKeypath Root keypath as determined by {@linkcode getRootHeaderKeypath}
+ * @param offset Numeric offset within the array of items for the header
+ * @param data Any parsed nav data found. For new items, this will be `undefined`. If not new, it
+ * may or may not have a `name` prop, and if it does, we want to retain it.
+ * @returns Complete keypath for a nav item beginning with the root keypath
+ */
+function getKeypathForHeaderItem(rootHeaderKeypath: string, offset: number, data?: ParsedNavData) {
+  return data?.name
+    ? `${rootHeaderKeypath}.${offset}.${data.name}`
+    : `${rootHeaderKeypath}.${offset}`;
+}
+
+/**
+ * Compares two sets of nav data and determines if they are different.
+ *
+ * This does not compare the entire `nav` object with a new one; it works per-header
+ * @param newNavData Nav data as computed by {@linkcode getNavItemsForDir} corresponding to a
+ * particular header
+ * @param navData Subset of original nav data as parsed by {@linkcode parseNav}, corresponding to
+ * the same header
+ */
+function navDataDidChange(
+  newNavData: Array<Omit<ParsedNavData, 'name'>>,
+  navData: ParsedNavData[]
+): boolean {
+  const diff = _.xorWith(
+    newNavData,
+    navData,
+    (a, b) => a.keypath === b.keypath && a.fileOrUrl === b.fileOrUrl
+  );
+  return !_.isEmpty(diff);
+}
+
+/**
+ * Find the "root" keypath for a particular header
+ * @param headerItems Some subset of the nav data having keypaths corresponding to `header`
+ * @param header Header string
+ * @returns The keypath up to the header string, inclusive
+ */
+function getRootHeaderKeypath(headerItems: ParsedNavData[], header: string) {
+  // these are the parts of the keypath of the first item, which will contain the header string. it
+  // dosn't matter whether we pick the first one or any one; they will all contain the same root
+  // keypath by definition.
+  const rootHeaderKeypathParts = _.toPath(_.first(headerItems)!.keypath);
+
+  // this is the keypath up to the header string, inclusive.
+  // we append indices or names to this keypath
+  return rootHeaderKeypathParts.slice(0, rootHeaderKeypathParts.indexOf(header) + 1).join('.');
+}
+
+/**
+ * This examines the `navData` looking for items matching the header string (which _may_ be defined
+ * by `dir`; if `all` is true, we just use the default header, because we will be returning a whole
+ * lot of headers).
+ *
+ *
+ * @param dir Abs path to directory containing markdown files generated by TypeDoc
+ * @param mkDocsDocsDir Configured `docs_dir` or via options
+ * @param navData Nav data parsed by {@linkcode parseNav}
+ * @param all If `true`, process all markdown files, not just commands
+ */
+async function getNavItemsForDir(
+  dir: string,
+  mkDocsDocsDir: string,
+  navData: ParsedNavData[],
+  nav: MkDocsYmlNav,
+  all = false
+) {
+  let dataChanged = false;
+  const newNavHeaderItems: Omit<ParsedNavData, 'name'>[] = [];
+  const referenceOutputFilepaths = await findRelativeMarkdownFiles(dir, mkDocsDocsDir);
+  if (!referenceOutputFilepaths.length) {
+    log.warn('No markdown files found in %s; did TypeDoc run?', dir);
+    return {data: [], changed: false};
+  }
+
+  const navHeader = all ? _.startCase(path.basename(dir)) : DEFAULT_NAV_HEADER;
+  const navHeaderItems = filterHeaderItems(navData, navHeader);
+
+  // if we found items with this header already, we are going
+  // to replace them all wholesale
+  if (navHeaderItems.length) {
+    log.debug('Found %d item(s) in header %s', navHeaderItems.length, navHeader);
+    // we append indices or names to this keypath
+    const rootHeaderKeypath = getRootHeaderKeypath(navHeaderItems, navHeader);
+
+    for (const fileOrUrl of referenceOutputFilepaths) {
+      let offset = navHeaderItems.findIndex((item) => item.fileOrUrl === fileOrUrl);
+      const newOffset = offset >= 0 ? offset : navHeaderItems.length;
+      const data = navHeaderItems[offset];
+      log.warn(rootHeaderKeypath, newOffset, data);
+      const keypath = getKeypathForHeaderItem(rootHeaderKeypath, newOffset, data);
+      newNavHeaderItems.push({keypath, fileOrUrl});
+    }
+
+    // look for any differences between what we have and what's in the file
+    if (navDataDidChange(newNavHeaderItems, navHeaderItems)) {
+      log.debug('Will write new nav data for header %s: %O', navHeader, newNavHeaderItems);
+      dataChanged = true;
+    } else {
+      log.debug('No changes for header %s', navHeader);
+    }
+  } else {
+    log.debug('No items found in header %s', navHeader);
+    let navOffset = nav.length;
+    for (const [idx, newRefFilepath] of referenceOutputFilepaths.entries()) {
+      newNavHeaderItems.push({
+        keypath: `${navOffset}.${navHeader}.${idx}`,
+        fileOrUrl: newRefFilepath,
+      });
+    }
+    log.debug('Will create nav data for header %s', navHeader);
+    dataChanged = true;
+  }
+  return {data: newNavHeaderItems, changed: dataChanged};
+}
+
+/**
+ * Applies the changes in `newData` to the `mkDocsYml` object.
+ *
+ * **This function mutates `mkDocsYml`.**
+ * @param newData New nav data
+ * @param mkDocsYml Original `mkdocs.yml`
+ */
+function applyNavData(newData: ParsedNavData[], mkDocsYml: MkDocsYml) {
+  for (const {keypath, fileOrUrl} of newData) {
+    _.set(mkDocsYml, `nav.${keypath}`, fileOrUrl);
+  }
+}
+
+/**
+ * Update the `nav` property of `mkdocs.yml` with a list of "command" files generated by TypeDoc via
+ * `@appium/typedoc-plugin-appium`.
+ *
+ * To be clear, this function **modifies the MkDocs config file (`mkdocs.yml`) in place**; it is
+ * typically under version control, so if this function makes any changes, you'll want to commit them.
+ * @param opts - Options
+ * @todo implement `dryRun` option
+ */
+export async function updateNav({
+  cwd = process.cwd(),
+  mkdocsYml: mkDocsYmlPath,
+  typedocJson: typeDocJsonPath,
+  all = false,
+  dryRun = false,
+}: UpdateNavOpts = {}) {
+  // we need `mkdocs.yml` to update
+  // and we need `typedoc.json` to know where to look for the command docs
+  [mkDocsYmlPath, typeDocJsonPath] = await Promise.all([
+    mkDocsYmlPath ?? findMkDocsYml(cwd),
+    typeDocJsonPath ?? findTypeDocJsonPath(cwd),
+  ]);
+  if (!mkDocsYmlPath) {
+    throw new DocutilsError(
+      `Could not find ${NAME_MKDOCS_YML} from ${cwd};  run "${NAME_BIN} init" to create it`
+    );
+  }
+  if (!typeDocJsonPath) {
+    throw new DocutilsError(
+      `Could not find ${NAME_TYPEDOC_JSON} from ${cwd};  run "${NAME_BIN} init" to create it`
+    );
+  }
+  const relativePath = relative(cwd);
+  const relMkDocsYmlPath = relativePath(mkDocsYmlPath);
+  const typeDocJson = readTypedocJson(typeDocJsonPath);
+  const mkDocsYml = (await readYaml(mkDocsYmlPath)) as MkDocsYml;
+
+  /**
+   * Absolute path to `typedoc.json`
+   */
+  const absTypeDocJsonPath = path.isAbsolute(typeDocJsonPath)
+    ? typeDocJsonPath
+    : path.resolve(cwd, typeDocJsonPath);
+
+  /**
+   * Absolute path to TypeDoc's output directory (`out`)
+   */
+  const typeDocOutDir = path.resolve(
+    path.dirname(absTypeDocJsonPath),
+    typeDocJson.out ? typeDocJson.out : DEFAULT_REL_TYPEDOC_OUT_PATH
+  );
+
+  /**
+   * Absolute path to `mkdocs.yml`
+   */
+  const absMkdocsYmlPath = path.isAbsolute(mkDocsYmlPath)
+    ? mkDocsYmlPath
+    : path.resolve(cwd, mkDocsYmlPath);
+
+  const {docs_dir: docsDir, nav = []} = mkDocsYml;
+  /**
+   * Absolute path to the directory containing MkDocs input docs
+   */
+  const mkDocsDocsDir = path.resolve(path.dirname(absMkdocsYmlPath), docsDir ?? 'docs');
+
+  /**
+   * @todo
+   * `commands` is a dirname configurable via the `commandsDir` option added by
+   * `@appium/typedoc-plugin-appium`. this lives in `typedoc.json`, but in order for it to be parsed
+   * using TypeDoc's facilities, we have to load plugins before reading `typedoc.json`, which is
+   * slow. we will probably have to support this in the future, but for now, we can just hardcode it
+   */
+  const dirs = all ? await findDirsIn(typeDocOutDir) : [path.join(typeDocOutDir, 'commands')];
+
+  let shouldWriteMkDocsYml = false;
+
+  const navData = parseNav(nav);
+
+  // this is the thing which will be assigned to the `nav` prop
+  // and thus written to `mkdocs.yml` if there were any changes.
+  // we don't need the `name` prop, since the name is already present in the keypath.
+  const newData: Omit<ParsedNavData, 'name'>[] = [];
+
+  for await (const dir of dirs) {
+    const {data, changed} = await getNavItemsForDir(dir, mkDocsDocsDir, navData, nav, all);
+    if (changed) {
+      shouldWriteMkDocsYml = true;
+    }
+    newData.push(...data);
+  }
+
+  if (shouldWriteMkDocsYml) {
+    applyNavData(newData, mkDocsYml);
+    const yaml = stringifyYaml(mkDocsYml);
+    log.debug('Writing to %s:\n%s', mkDocsYmlPath, yaml);
+    await safeWriteFile(mkDocsYmlPath, yaml, true);
+    log.success(
+      'Updated MkDocs navigation config for reference docs; please run "git add -A %s" and commit this change',
+      relMkDocsYmlPath
+    );
+  } else {
+    log.info('No changes needed for MkDocs config at %s', relMkDocsYmlPath);
+  }
+}
+
+/**
+ * Options for {@linkcode updateNav}
+ */
+export interface UpdateNavOpts {
+  /**
+   * Current working directory
+   */
+  cwd?: string;
+  /**
+   * Path to `mkdocs.yml`
+   */
+  mkdocsYml?: string;
+  /**
+   * Path to `package.json`
+   */
+  packageJson?: string;
+  /**
+   * Path to `typedoc.json`
+   */
+  typedocJson?: string;
+  /**
+   * If `true`, do not write any files
+   * @remarks Not yet implemented
+   */
+  dryRun?: boolean;
+
+  /**
+   * If `true`, add _all_ reference documentation to the navigation config (not just commands)
+   */
+  all?: boolean;
+}
+
+/**
+ * Used internally by {@linkcode updatedNav}
+ * @see {@linkcode parseNav}
+ */
+interface ParsedNavData {
+  /**
+   * Keypath within `nav` for some file or URL
+   */
+  keypath: string;
+  /**
+   * A filepath (usually) or a URL.
+   * This is considered the "index" of the data, and should be unique within its parent. If it's not
+   * unique, then it will probably end up that way after updating...
+   */
+  fileOrUrl: string;
+  /**
+   * If this file or url has a proper name, this would be it. Most don't.
+   */
+  name?: string;
+}