@appium/docutils 0.1.6 → 0.2.0

package/build/lib/validate.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Validates an environment for building documentation
+ *
+ * @module
+ */
+/// <reference types="node" />
+import { EventEmitter } from 'node:events';
+import { NAME_MKDOCS, NAME_NPM, NAME_PYTHON, NAME_TYPEDOC, NAME_TYPESCRIPT } from './constants';
+import { DocutilsError } from './error';
+import { PipPackage } from './model';
+/**
+ * The "kinds" of validation which were requested to be performed
+ */
+export declare type ValidationKind = typeof NAME_PYTHON | typeof NAME_TYPESCRIPT | typeof NAME_TYPEDOC | typeof NAME_NPM | typeof NAME_MKDOCS;
+/**
+ * This class is designed to run _all_ validation checks (as requested by the user), and emit events for
+ * each failure encountered.
+ *
+ * Whenever a method _rejects or throws_, this is considered an "unexpected" error, and the validation
+ * will abort.
+ *
+ * @todo Use [`strict-event-emitter-types`](https://npm.im/strict-event-emitter-types)
+ */
+export declare class DocutilsValidator extends EventEmitter {
+    /**
+     * Current working directory. Defaults to `process.cwd()`
+     * @todo This cannot yet be overriden by user
+     */
+    protected readonly cwd: string;
+    /**
+     * Path to `npm` executable.
+     */
+    protected readonly npmPath: string | undefined;
+    /**
+     * Path to `python` executable.
+     */
+    protected readonly pythonPath: string | undefined;
+    /**
+     * List of validations to perform
+     */
+    protected readonly validations: Set<ValidationKind>;
+    /**
+     * Mapping of error messages to errors.
+     *
+     * Used to prevent duplicate emission of errors and track error count; if non-empty, the validation
+     * process should be considered to have failed.
+     *
+     * Reset after {@linkcode DocutilsValidator.validate validate} completes.
+     */
+    protected emittedErrors: Map<string, DocutilsError>;
+    /**
+     * Path to `mkdocs.yml`.  If not provided, will be lazily resolved.
+     */
+    protected mkDocsYmlPath: string | undefined;
+    /**
+     * Path to `package.json`.  If not provided, will be lazily resolved.
+     */
+    protected packageJsonPath: string | undefined;
+    /**
+     * Path to the package directory.  If not provided, will be lazily resolved.
+     */
+    protected pkgDir: string | undefined;
+    /**
+     * Path to `tsconfig.json`.  If not provided, will be lazily resolved.
+     */
+    protected tsconfigJsonPath: string | undefined;
+    /**
+     * Path to `typedoc.json`.  If not provided, will be lazily resolved.
+     */
+    protected typeDocJsonPath: string | undefined;
+    /**
+     * Emitted when validation begins with a list of validation kinds to be performed
+     * @event
+     */
+    static readonly BEGIN = "begin";
+    /**
+     * Emitted when validation ends with an error count
+     * @event
+     */
+    static readonly END = "end";
+    /**
+     * Emitted when a validation fails, with the associated {@linkcode DocutilsError}
+     * @event
+     */
+    static readonly FAILURE = "fail";
+    /**
+     * Emitted when a validation succeeds
+     * @event
+     */
+    static readonly SUCCESS = "ok";
+    private requirementsTxt;
+    /**
+     * Creates a listener to track errors emitted
+     */
+    constructor(opts?: DocutilsValidatorOpts);
+    /**
+     * Runs the configured validations, then resets internal state upon completion or rejection.
+     */
+    validate(): Promise<void>;
+    /**
+     * If a thing like `err` has not already been emitted, emit
+     * {@linkcode DocutilsValidator.FAILURE}.
+     * @param err A validation error
+     * @returns
+     */
+    protected fail(err: DocutilsError | string): void;
+    /**
+     * Resolves with a the parent directory of `package.json`, if we can find it.
+     */
+    protected findPkgDir(): Promise<string | undefined>;
+    /**
+     * Emits a {@linkcode DocutilsValidator.SUCCESS} event
+     * @param message Success message
+     */
+    protected ok(message: string): void;
+    /**
+     * Parses a `requirements.txt` file and returns an array of packages
+     *
+     * Caches the result.
+     * @returns List of package data w/ name and version
+     */
+    protected parseRequirementsTxt(): Promise<PipPackage[]>;
+    /**
+     * Resets the cache of emitted errors
+     */
+    protected reset(): void;
+    protected validateMkDocs(): Promise<void>;
+    /**
+     * Validates (sort of) an `mkdocs.yml` config file.
+     *
+     * It checks if the file exists, if it can be parsed as YAML, and if it has a `site_name` property.
+     */
+    protected validateMkDocsConfig(mkDocsYmlPath?: string): Promise<void>;
+    /**
+     * 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 validateNpmVersion(): Promise<void>;
+    /**
+     * Asserts that the dependencies as listed in `requirements.txt` are installed.
+     *
+     * @privateRemarks This lists all installed packages with `pip` and then compares them to the
+     * contents of our `requirements.txt`. Versions _must_ match exactly.
+     */
+    protected validatePythonDeps(): Promise<void>;
+    /**
+     * Asserts that the Python version is 3.x
+     */
+    protected validatePythonVersion(): Promise<void>;
+    /**
+     * Asserts TypeDoc is installed, runnable, the correct version, and that the config file is readable
+     * and constaints required options
+     */
+    protected validateTypeDoc(): Promise<void>;
+    /**
+     * Validates the `typedoc.json` file
+     */
+    protected validateTypeDocConfig(): Promise<void>;
+    /**
+     * Asserts that TypeScript is installed, runnable, the correct version, and a parseable `tsconfig.json` exists.
+     */
+    protected validateTypeScript(): Promise<void>;
+    /**
+     * Validates a `tsconfig.json` file
+     */
+    protected validateTypeScriptConfig(): Promise<void>;
+}
+/**
+ * Options for {@linkcode DocutilsValidator} constructor
+ */
+export interface DocutilsValidatorOpts {
+    /**
+     * Current working directory
+     */
+    cwd?: string;
+    /**
+     * Path to `mkdocs.yml`
+     */
+    mkdocsYml?: string;
+    /**
+     * Path to `npm` executable
+     */
+    npm?: string;
+    /**
+     * Path to `package.json`
+     */
+    packageJson?: string;
+    /**
+     * If `true`, run Python validation
+     */
+    python?: boolean;
+    /**
+     * Path to `python` executable
+     */
+    pythonPath?: string;
+    /**
+     * Path to `tsconfig.json`
+     */
+    tsconfigJson?: string;
+    /**
+     * If `true`, run TypeDoc validation
+     */
+    typedoc?: boolean;
+    /**
+     * Path to `typedoc.json`
+     */
+    typedocJson?: string;
+    /**
+     * If `true`, run TypeScript validation
+     */
+    typescript?: boolean;
+    /**
+     * If `true`, run MkDocs validation
+     */
+    mkdocs?: boolean;
+}
+//# sourceMappingURL=validate.d.ts.map

package/build/lib/validate.d.ts.map

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