@appium/docutils 1.1.1 → 2.0.0

package/lib/constants.ts

@@ -4,10 +4,8 @@
  */
 
 const {LogLevels} = require('consola');
-import {readFileSync} from 'node:fs';
 import {fs} from '@appium/support';
 import path from 'node:path';
-import {PackageJson} from 'type-fest';
 
 /**
  * CLI executable name
@@ -19,10 +17,6 @@ export const NAME_BIN = 'appium-docs';
  */
 export const NAME_MKDOCS_YML = 'mkdocs.yml';
 
-/**
- * Default name of the `tsconfig.json` config file
- */
-export const NAME_TSCONFIG_JSON = 'tsconfig.json';
 /**
  * `python` executable
  */
@@ -58,16 +52,6 @@ export const NAME_MIKE = 'mike';
  */
 export const NAME_PIP = 'pip';
 
-/**
- * Name of the `npm` executable, which we use to check for
- */
-export const NAME_NPM = 'npm';
-
-/**
- * The name of the `typescript` package (not the `tsc` executable)
- */
-export const NAME_TYPESCRIPT = 'typescript';
-
 /**
  * Code for a "file not found" error
  */
@@ -86,13 +70,6 @@ export const DEFAULT_LOG_LEVEL = 'info';
  * Blocking I/O
  */
 export const PKG_ROOT_DIR = fs.findRoot(__dirname);
-/**
- * Blocking I/O
- */
-
-export const DOCUTILS_PKG: PackageJson = JSON.parse(
-  readFileSync(path.join(PKG_ROOT_DIR, NAME_PACKAGE_JSON), 'utf8'),
-);
 
 /**
  * Path to the `requirements.txt` file (in this package)

package/lib/fs.ts

@@ -4,7 +4,6 @@
  */
 
 import {fs} from '@appium/support';
-import * as JSON5 from 'json5';
 import _ from 'lodash';
 import path from 'node:path';
 import _pkgDir from 'pkg-dir';
@@ -16,7 +15,6 @@ import {
   NAME_MIKE,
   NAME_MKDOCS,
   NAME_MKDOCS_YML,
-  NAME_NPM,
   NAME_PACKAGE_JSON,
   NAME_PYTHON,
 } from './constants';
@@ -32,7 +30,7 @@ const log = getLogger('fs');
  *
  * Caches result
  */
-export const findPkgDir = _.memoize(_pkgDir);
+const findPkgDir = _.memoize(_pkgDir);
 
 /**
  * Stringifies a thing into a YAML
@@ -45,16 +43,6 @@ export const stringifyYaml: (value: JsonValue) => string = _.partialRight(
   undefined,
 );
 
-/**
- * Stringifies something into JSON5.  I think the only difference between this and `JSON.stringify`
- * is that if an object has a `toJSON5()` method, it will be used.
- * @param value Something to stringify
- * @returns JSON5 string
- */
-export const stringifyJson5: (value: JsonValue) => string = _.partialRight(JSON5.stringify, {
-  indent: 2,
-});
-
 /**
  * Pretty-stringifies a JSON value
  * @param value Something to stringify
@@ -143,14 +131,6 @@ async function _readPkgJson(
  */
 export const readPackageJson = _.memoize(_readPkgJson);
 
-/**
- * Reads a JSON5 file and parses it
- */
-export const readJson5 = _.memoize(
-  async <T extends JsonValue>(filepath: string): Promise<T> =>
-    JSON5.parse(await fs.readFile(filepath, 'utf8')),
-);
-
 /**
  * Reads a JSON file and parses it
  */
@@ -178,11 +158,6 @@ type WhichFunction = (cmd: string, opts?: {nothrow: boolean}) => Promise<string|
  */
 const cachedWhich = _.memoize(fs.which as WhichFunction);
 
-/**
- * Finds `npm` executable
- */
-export const whichNpm = _.partial(cachedWhich, NAME_NPM, {nothrow: true});
-
 /**
  * Finds `python` executable
  */

package/lib/init.ts

@@ -4,8 +4,7 @@
  * @module
  */
 
-import * as JSON5 from 'json5';
-import {NAME_MKDOCS_YML, NAME_TSCONFIG_JSON, PIP_ENV_VARS, REQUIREMENTS_TXT_PATH} from './constants';
+import {NAME_MKDOCS_YML, PIP_ENV_VARS, REQUIREMENTS_TXT_PATH} from './constants';
 import YAML from 'yaml';
 import {exec} from 'teen_process';
 import {Simplify} from 'type-fest';
@@ -13,9 +12,8 @@ import {DocutilsError} from './error';
 import {createScaffoldTask, ScaffoldTaskOptions} from './scaffold';
 import type { ScaffoldTask } from './scaffold';
 import {getLogger} from './logger';
-import {MkDocsYml, TsConfigJson} from './model';
-import _ from 'lodash';
-import {requirePython, stringifyJson5, stringifyYaml} from './fs';
+import {MkDocsYml} from './model';
+import {requirePython, stringifyYaml} from './fs';
 
 /**
  * Data for the base `mkdocs.yml` file
@@ -26,54 +24,9 @@ const BASE_MKDOCS_YML: Readonly<MkDocsYml> = Object.freeze({
   site_dir: 'site',
 });
 
-/**
- * Data for the base `tsconfig.json` file
- */
-const BASE_TSCONFIG_JSON: Readonly<TsConfigJson> = Object.freeze({
-  $schema: 'https://json.schemastore.org/tsconfig',
-  extends: '@appium/tsconfig/tsconfig.json',
-  compilerOptions: {
-    outDir: 'build',
-  },
-});
-
 const log = getLogger('init');
 const dryRunLog = getLogger('dry-run', log);
 
-/**
- * Files included, by default, in `tsconfig.json`
- */
-const DEFAULT_INCLUDE = ['lib', 'test', 'index.js'];
-/**
- * Function which scaffolds a `tsconfig.json` file
- */
-export const initTsConfigJson = createScaffoldTask<InitTsConfigOptions, TsConfigJson>(
-  NAME_TSCONFIG_JSON,
-  BASE_TSCONFIG_JSON,
-  'TypeScript configuration',
-  {
-    /**
-     * Merges the contents of the `include` property with any passed on the CLI. If neither exists,
-     * uses the default set of includes.
-     * @param content Parsed and/or scaffolded `tsconfig.json`
-     * @param opts Options specific to this task
-     * @returns `tsconfig.json` content with potentially-modified `include` prop
-     */
-    transform: (content, {include}) => {
-      include = [...(content.include ?? include ?? [])];
-      if (_.isEmpty(include)) {
-        include = [...DEFAULT_INCLUDE];
-      }
-      return {
-        ...content,
-        include: _.uniq(include),
-      };
-    },
-    deserialize: JSON5.parse,
-    serialize: stringifyJson5,
-  },
-);
-
 /**
  * Function which scaffolds an `mkdocs.yml` file
  */
@@ -192,12 +145,9 @@ export interface InitMkDocsOptions extends ScaffoldTaskOptions {
  * console output which would need mitigation.
  */
 export async function init({
-  typescript,
   python,
-  tsconfigJson: tsconfigJsonPath,
   packageJson: packageJsonPath,
   overwrite,
-  include,
   mkdocs,
   mkdocsYml: mkdocsYmlPath,
   siteName,
@@ -209,17 +159,6 @@ export async function init({
   pythonPath,
   upgrade,
 }: InitOptions = {}): Promise<void> {
-  if (typescript && !upgrade) {
-    await initTsConfigJson({
-      dest: tsconfigJsonPath,
-      packageJson: packageJsonPath,
-      overwrite,
-      include,
-      dryRun,
-      cwd,
-    });
-  }
-
   if (python) {
     await initPython({pythonPath, dryRun, upgrade});
   }
@@ -239,12 +178,6 @@ export async function init({
   }
 }
 
-export interface InitTsConfigOptions extends ScaffoldTaskOptions {
-  /**
-   * List of source files (globs supported); typically `src` or `lib`
-   */
-  include?: string[];
-}
 export interface InitPythonOptions extends ScaffoldTaskOptions {
   /**
    * Path to `python` (v3.x) executable
@@ -263,11 +196,7 @@ export interface InitPythonOptions extends ScaffoldTaskOptions {
  * The props of the various "path" options are rewritten as `dest` for the scaffold tasks functions.
  */
 export type InitOptions = Simplify<
-  Omit<InitPythonOptions & InitTsConfigOptions & InitMkDocsOptions, 'dest'> & {
-    /**
-     * If `true` will initialize a `tsconfig.json` file
-     */
-    typescript?: boolean;
+  Omit<InitPythonOptions & InitMkDocsOptions, 'dest'> & {
     /**
      * If `true` will install Python deps
      */
@@ -276,10 +205,6 @@ export type InitOptions = Simplify<
      * If `true` will initialize a `mkdocs.yml` file
      */
     mkdocs?: boolean;
-    /**
-     * Path to new or existing `tsconfig.json` file
-     */
-    tsconfigJson?: string;
     /**
      * Path to existing `package.json` file
      */

package/lib/model.ts

@@ -4,14 +4,7 @@
  * @module
  */
 
-import type {Jsonify, JsonValue, TsConfigJson as TsConfigJsonBase} from 'type-fest';
-
-/**
- * A `tsconfig.json` file w/ `$schema` prop
- */
-export type TsConfigJson = TsConfigJsonBase & {
-  $schema?: string;
-};
+import type {Jsonify, JsonValue} from 'type-fest';
 
 /**
  * The `nav` prop of an `mkdocs.yml` file

package/lib/validate.ts

@@ -4,53 +4,37 @@
  * @module
  */
 
-import {fs, npm, util} from '@appium/support';
+import {fs, util} from '@appium/support';
 import chalk from 'chalk';
 import _ from 'lodash';
 import {EventEmitter} from 'node:events';
-import path from 'node:path';
-import {satisfies} from 'semver';
 import {exec} from 'teen_process';
 import {
-  DOCUTILS_PKG,
   MESSAGE_PYTHON_MISSING,
   NAME_BIN,
   NAME_ERR_ENOENT,
   NAME_MKDOCS,
   NAME_MKDOCS_YML,
-  NAME_NPM,
-  NAME_PACKAGE_JSON,
   NAME_PIP,
   NAME_PYTHON,
   NAME_REQUIREMENTS_TXT,
-  NAME_TSCONFIG_JSON,
-  NAME_TYPESCRIPT,
   REQUIREMENTS_TXT_PATH,
 } from './constants';
 import {DocutilsError} from './error';
 import {
   findMkDocsYml,
-  findPkgDir,
   isMkDocsInstalled,
-  readJson5,
   readMkDocsYml,
-  whichNpm,
   findPython,
 } from './fs';
 import {getLogger} from './logger';
 import {MkDocsYml, PipPackage} from './model';
-import {relative} from './util';
 
 /**
  * Matches the Python version string from `python --version`
  */
 const PYTHON_VER_STR = 'Python 3.';
 
-/**
- * Matches the TypeScript version string from `tsc --version`
- */
-const TYPESCRIPT_VERSION_REGEX = /Version\s(\d+\.\d+\..+)/;
-
 /**
  * Matches the MkDocs version string from `mkdocs --version`
  */
@@ -61,11 +45,7 @@ const log = getLogger('validate');
 /**
  * The "kinds" of validation which were requested to be performed
  */
-export type ValidationKind =
-  | typeof NAME_PYTHON
-  | typeof NAME_TYPESCRIPT
-  | typeof NAME_NPM
-  | typeof NAME_MKDOCS;
+export type ValidationKind = typeof NAME_PYTHON | typeof NAME_MKDOCS;
 
 /**
  * This class is designed to run _all_ validation checks (as requested by the user), and emit events for
@@ -83,11 +63,6 @@ export class DocutilsValidator extends EventEmitter {
    */
   protected readonly cwd: string;
 
-  /**
-   * Path to `npm` executable.
-   */
-  protected readonly npmPath?: string;
-
   /**
    * Path to `python` executable.
    */
@@ -113,21 +88,6 @@ export class DocutilsValidator extends EventEmitter {
    */
   protected mkDocsYmlPath?: string;
 
-  /**
-   * Path to `package.json`.  If not provided, will be lazily resolved.
-   */
-  protected packageJsonPath?: string;
-
-  /**
-   * Path to the package directory.  If not provided, will be lazily resolved.
-   */
-  protected pkgDir?: string;
-
-  /**
-   * Path to `tsconfig.json`.  If not provided, will be lazily resolved.
-   */
-  protected tsconfigJsonPath?: string;
-
   /**
    * Emitted when validation begins with a list of validation kinds to be performed
    * @event
@@ -160,21 +120,13 @@ export class DocutilsValidator extends EventEmitter {
   constructor(opts: DocutilsValidatorOpts = {}) {
     super();
 
-    this.packageJsonPath = opts.packageJson;
     this.pythonPath = opts.pythonPath;
     this.cwd = opts.cwd ?? process.cwd();
-    this.tsconfigJsonPath = opts.tsconfigJson;
-    this.npmPath = opts.npm;
     this.mkDocsYmlPath = opts.mkdocsYml;
 
     if (opts.python) {
       this.validations.add(NAME_PYTHON);
     }
-    if (opts.typescript) {
-      this.validations.add(NAME_TYPESCRIPT);
-      // npm validation is required for typescript
-      this.validations.add(NAME_NPM);
-    }
     if (opts.mkdocs) {
       this.validations.add(NAME_MKDOCS);
     }
@@ -202,15 +154,6 @@ export class DocutilsValidator extends EventEmitter {
         await this.validateMkDocsConfig();
       }
 
-      if (this.validations.has(NAME_NPM)) {
-        await this.validateNpmVersion();
-      }
-
-      if (this.validations.has(NAME_TYPESCRIPT)) {
-        await this.validateTypeScript();
-        await this.validateTypeScriptConfig();
-      }
-
       this.emit(DocutilsValidator.END, this.emittedErrors.size);
     } finally {
       this.reset();
@@ -230,18 +173,6 @@ export class DocutilsValidator extends EventEmitter {
     }
   }
 
-  /**
-   * Resolves with a the parent directory of `package.json`, if we can find it.
-   */
-  protected async findPkgDir(): Promise<string | undefined> {
-    return (
-      this.pkgDir ??
-      (this.pkgDir = this.packageJsonPath
-        ? path.dirname(this.packageJsonPath)
-        : await findPkgDir(this.cwd))
-    );
-  }
-
   /**
    * Emits a {@linkcode DocutilsValidator.SUCCESS} event
    * @param message Success message
@@ -363,35 +294,6 @@ export class DocutilsValidator extends EventEmitter {
     this.ok(`MkDocs config at ${mkDocsYmlPath} OK`);
   }
 
-  /**
-   * Validates that the version of `npm` matches what's described in this package's `engines` field.
-   *
-   * This is required because other validators need `npm exec` to work, which is only available in npm 7+.
-   */
-  protected async validateNpmVersion() {
-    log.debug(`Validating ${NAME_NPM} version`);
-
-    const npmEngineRange = DOCUTILS_PKG.engines?.npm;
-    if (!npmEngineRange) {
-      throw new DocutilsError(`Could not find property 'engines.npm' in ${NAME_PACKAGE_JSON}. This is a bug`);
-    }
-
-    const npmPath = this.npmPath ?? (await whichNpm());
-    if (!npmPath) {
-      throw new DocutilsError(`Could not find ${NAME_NPM} in PATH. That seems weird, doesn't it?`);
-    }
-
-    try {
-      const {stdout: npmVersion} = await npm.exec('-v', [], {cwd: this.cwd});
-      if (!satisfies(npmVersion.trim(), npmEngineRange)) {
-        return this.fail(`${NAME_NPM} v${npmVersion} is installed, but ${npmEngineRange} is required`);
-      }
-    } catch {
-      return this.fail(`Could not retrieve ${NAME_NPM} version`);
-    }
-    this.ok(`${NAME_NPM} version OK`);
-  }
-
   /**
    * Asserts that the dependencies as listed in `requirements.txt` are installed.
    *
@@ -495,83 +397,6 @@ export class DocutilsValidator extends EventEmitter {
     }
     this.ok('Python version OK');
   }
-
-  /**
-   * Asserts that TypeScript is installed, runnable, and the correct version.
-   */
-  protected async validateTypeScript() {
-    log.debug(`Validating ${NAME_TYPESCRIPT} version`);
-
-    const pkgDir = await this.findPkgDir();
-    if (!pkgDir) {
-      return this.fail(`Could not find ${NAME_PACKAGE_JSON} in ${this.cwd}`);
-    }
-
-    const npmPath = this.npmPath ?? (await whichNpm());
-    if (!npmPath) {
-      throw new DocutilsError(`Could not find ${NAME_NPM} in PATH. That seems weird, doesn't it?`);
-    }
-
-    let typeScriptVersion: string;
-    let rawTypeScriptVersion: string;
-    try {
-      ({stdout: rawTypeScriptVersion} = await npm.exec('exec', ['tsc', '--', '--version'], {
-        cwd: pkgDir,
-      }));
-    } catch {
-      return this.fail(`Could not find TypeScript compiler ("tsc") from ${pkgDir}`);
-    }
-
-    const match = rawTypeScriptVersion.match(TYPESCRIPT_VERSION_REGEX);
-    if (match) {
-      typeScriptVersion = match[1];
-    } else {
-      return this.fail(
-        `Could not parse TypeScript version from "tsc --version"; output was:\n ${rawTypeScriptVersion}`,
-      );
-    }
-
-    const reqdTypeScriptVersion = DOCUTILS_PKG.dependencies?.typescript;
-    if (!reqdTypeScriptVersion) {
-      throw new DocutilsError(
-        `Could not find ${NAME_TYPESCRIPT} dependency in ${NAME_PACKAGE_JSON}. This is a bug`,
-      );
-    }
-
-    if (!satisfies(typeScriptVersion, reqdTypeScriptVersion)) {
-      return this.fail(
-        `TypeScript v${typeScriptVersion} is installed, but v${reqdTypeScriptVersion} is required`,
-      );
-    }
-    this.ok('TypeScript install OK');
-  }
-
-  /**
-   * Validates a `tsconfig.json` file
-   */
-  protected async validateTypeScriptConfig() {
-    log.debug(`Validating ${NAME_TSCONFIG_JSON}`);
-
-    const pkgDir = await this.findPkgDir();
-    if (!pkgDir) {
-      return this.fail(`Could not find ${NAME_PACKAGE_JSON} in ${this.cwd}`);
-    }
-
-    const tsconfigJsonPath = this.tsconfigJsonPath ?? path.join(pkgDir, NAME_TSCONFIG_JSON);
-    const relTsconfigJsonPath = relative(this.cwd, tsconfigJsonPath);
-    try {
-      await readJson5(tsconfigJsonPath);
-    } catch (e) {
-      if (e instanceof SyntaxError) {
-        return this.fail(`Could not parse ${NAME_TSCONFIG_JSON} at ${relTsconfigJsonPath}: ${e}`);
-      }
-      return this.fail(
-        `Could not find ${NAME_TSCONFIG_JSON} at ${relTsconfigJsonPath}; please run "${NAME_BIN} init"`,
-      );
-    }
-
-    this.ok('TypeScript config OK');
-  }
 }
 
 /**
@@ -587,14 +412,6 @@ export interface DocutilsValidatorOpts {
    * Path to `mkdocs.yml`
    */
   mkdocsYml?: string;
-  /**
-   * Path to `npm` executable
-   */
-  npm?: string;
-  /**
-   * Path to `package.json`
-   */
-  packageJson?: string;
   /**
    * If `true`, run Python validation
    */
@@ -603,14 +420,6 @@ export interface DocutilsValidatorOpts {
    * Path to `python` executable
    */
   pythonPath?: string;
-  /**
-   * Path to `tsconfig.json`
-   */
-  tsconfigJson?: string;
-  /**
-   * If `true`, run TypeScript validation
-   */
-  typescript?: boolean;
   /**
    * If `true`, run MkDocs validation
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/docutils",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "Documentation generation utilities for Appium and related projects",
   "keywords": [
     "automation",
@@ -48,32 +48,27 @@
     "start": "node ./build/lib/cli/index.js"
   },
   "dependencies": {
-    "@appium/support": "^6.1.1",
-    "@appium/tsconfig": "^0.3.5",
-    "@sliphua/lilconfig-ts-loader": "3.2.2",
+    "@appium/support": "^7.0.0",
     "chalk": "4.1.2",
     "consola": "3.4.2",
-    "diff": "8.0.2",
-    "json5": "2.2.3",
+    "diff": "8.0.02",
     "lilconfig": "3.1.3",
     "lodash": "4.17.21",
     "pkg-dir": "5.0.0",
     "read-pkg": "5.2.0",
-    "semver": "7.7.2",
     "source-map-support": "0.5.21",
-    "teen_process": "2.3.2",
+    "teen_process": "3.0.0",
     "type-fest": "4.41.0",
-    "typescript": "5.8.3",
-    "yaml": "2.8.0",
-    "yargs": "17.7.2",
-    "yargs-parser": "21.1.1"
+    "yaml": "2.8.1",
+    "yargs": "18.0.0",
+    "yargs-parser": "22.0.0"
   },
   "engines": {
-    "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
-    "npm": ">=8"
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
+    "npm": ">=10"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "c8fe4412525f7e1fa237813cf83fe7d98f0125eb"
+  "gitHead": "284da50353921343fa5a7f82574e64ce0c146db7"
 }

package/requirements.txt

@@ -1,5 +1,5 @@
 mkdocs==1.6.1
 mkdocs-git-revision-date-localized-plugin==1.4.7
-mkdocs-material==9.6.14
+mkdocs-material==9.6.17
 mkdocs-redirects==1.2.2
 mike==2.1.3