@appium/docutils 0.4.12 → 1.0.1

package/build/lib/mike.js

@@ -1,146 +0,0 @@
-"use strict";
-/**
- * API around `mike`, a tool for deploying multiple versions of MkDocs-built sites to GitHub Pages
- * @module
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Mike = void 0;
-const teen_process_1 = require("teen_process");
-// eslint-disable-next-line import/no-unresolved
-const logger_1 = __importDefault(require("./logger"));
-const DEFAULT_REMOTE = 'origin';
-const DEFAULT_BRANCH = 'gh-pages';
-const MIKE_VER_STRING = 'mike 1.';
-/**
- * @deprecated Use the `deploy` export from `@appium/docutils`
- */
-class Mike {
-    constructor(/** @type MikeOpts */ opts) {
-        /** @type {boolean} */ this._mikeVerified = false;
-        this.remote = opts.remote || DEFAULT_REMOTE;
-        this.branch = opts.branch || DEFAULT_BRANCH;
-        this.prefix = opts.prefix;
-        this.configFile = opts.configFile;
-    }
-    /**
-     * Throw an error if the 'mike' binary cannot be found
-     *
-     * @throws {Error}
-     */
-    async verifyMike() {
-        if (this._mikeVerified) {
-            return;
-        }
-        try {
-            const { stdout } = await this.exec('--version', [], false);
-            if (!stdout.includes(MIKE_VER_STRING)) {
-                throw new Error('Mike was installed but was not version 1.x');
-            }
-        }
-        catch (err) {
-            throw new Error(`Could not verify appropriate mike binary exists: ${err}`);
-        }
-        this._mikeVerified = true;
-    }
-    /**
-     * Get an array of args based on the class members that can be used with Mike-related subprocess
-     * execution
-     *
-     * @param {string} cmdName - the name of the mike command to run
-     * @param {string[]} cmdArgs - an array of command-specific arguments
-     *
-     * @returns {string[]}
-     */
-    getMikeArgs(cmdName, cmdArgs) {
-        return [
-            cmdName,
-            ...cmdArgs,
-            '--config-file',
-            this.configFile,
-            '--remote',
-            this.remote,
-            '--branch',
-            this.branch,
-            '--prefix',
-            this.prefix,
-        ];
-    }
-    /**
-     * Exec mike as a subprocess
-     *
-     * @param {string} mikeCmd - the mike command to run
-     * @param {string[]} [mikeArgs=[]] - the arguments to pass to the mike command
-     * @param {boolean?} [verify=true] - whether to verify mike exists first
-     *
-     * @returns {Promise<import('teen_process').ExecResult<string>>}
-     */
-    async exec(mikeCmd, mikeArgs = [], verify = true) {
-        if (verify) {
-            await this.verifyMike();
-        }
-        const args = this.getMikeArgs(mikeCmd, mikeArgs);
-        logger_1.default.debug(`Running mike ${args.join(' ')}`);
-        return await (0, teen_process_1.exec)('mike', args);
-    }
-    /**
-     * Return the list of mike deploys
-     *
-     * @returns {string[]}
-     */
-    async list() {
-        const { stdout } = await this.exec('list');
-        return stdout
-            .split('\n')
-            .map((s) => s.trim())
-            .filter(Boolean);
-    }
-    /**
-     * Set the default version or alias
-     *
-     * @param {string} alias - the version or alias
-     */
-    async setDefault(alias) {
-        await this.exec('set-default', [alias]);
-    }
-    /**
-     * Deploy docs to the branch
-     *
-     * @param {MikeDeployOpts} opts - the deploy options
-     */
-    async deploy(opts) {
-        const args = [opts.version];
-        if (opts.alias) {
-            args.push(opts.alias, '--update-aliases');
-        }
-        if (opts.shouldPush) {
-            args.push('--push');
-        }
-        if (opts.shouldRebase) {
-            args.push('--rebase');
-        }
-        if (opts.commit) {
-            args.push('--message', opts.commit);
-        }
-        await this.exec('deploy', args);
-    }
-}
-exports.Mike = Mike;
-/**
- * @typedef MikeOpts - options for instantiating a Mike object
- * @property {string} [remote="origin"] - the git remote to push docs to
- * @property {string} [branch="gh-pages"] - the git branch to push docs to
- * @property {string?} prefix - the path prefix on the branch if any
- * @property {string} configFile - the mkdocs config file to use
- */
-/**
- * @typedef MikeDeployOpts - options for deploying docs with Mike
- * @param {string} version - the version to deploy
- * @param {string?} alias - the alias to alias (or re-alias) the version
- * @param {string?} commit - the commit message to use as an override
- * @param {boolean?} shouldPush - whether mike should push the commits to the remote
- * @param {boolean?} shouldRebase - whether mike should rebase
- */
-//# sourceMappingURL=mike.js.map

package/build/lib/mike.js.map

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

package/lib/builder/nav.ts

@@ -1,402 +0,0 @@
-/**
- * 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 {getLogger} from '../logger';
-import {MkDocsYml, MkDocsYmlNav} from '../model';
-import {relative} from '../util';
-
-const log = getLogger('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) {
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    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));
-}
-
-/**
- * Given a root header keypath (like a prefix), a numeric offset, and some parsed nav data, compute
- * a keypath
- *
- * @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 {
-  // the result should be the items from newNavData which either don't appear in
-  // navdata, or the items which do appear in navData but have a different fileOrUrl
-  const matchedKeypaths = _.intersectionBy(newNavData, navData, 'keypath');
-  const diff = _.xorBy(newNavData, matchedKeypaths, '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.
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  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) {
-      const offset = navHeaderItems.findIndex((item) => item.fileOrUrl === fileOrUrl);
-      const newOffset = offset >= 0 ? offset : navHeaderItems.length;
-      const data = navHeaderItems[offset];
-      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);
-    const 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,
-}: 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;
-}