text-runner-engine 7.1.0

package/dist/commands/static.js

@@ -0,0 +1,60 @@
+import { EventEmitter } from "events";
+import * as actions from "../actions/index.js";
+import { extractImagesAndLinks } from "../activities/extract-images-and-links.js";
+import * as configuration from "../configuration/index.js";
+import * as files from "../filesystem/index.js";
+import * as linkTargets from "../link-targets/index.js";
+import * as parser from "../parsers/index.js";
+import * as run from "../run/index.js";
+import * as workspace from "../workspace/index.js";
+export class Static {
+    constructor(userConfig) {
+        this.userConfig = userConfig;
+        this.emitter = new EventEmitter();
+    }
+    emit(name, payload) {
+        this.emitter.emit(name, payload);
+    }
+    async execute() {
+        const originalDir = process.cwd();
+        try {
+            // step 1: determine full configuration
+            const config = await configuration.addDefaults(this.userConfig);
+            // step 2: create working dir
+            await workspace.create(config);
+            // step 3: find files
+            const filenames = await files.getFileNames(config);
+            if (filenames.length === 0) {
+                this.emit("result", { message: "no Markdown files found", status: "warning" });
+                return;
+            }
+            // step 4: read and parse files
+            const ASTs = await parser.markdown.parse(filenames, config.sourceDir);
+            // step 5: find link targets
+            const targets = linkTargets.find(ASTs);
+            // step 6: extract activities
+            const links = extractImagesAndLinks(ASTs);
+            if (links.length === 0) {
+                this.emit("result", { message: "no activities found", status: "warning" });
+                return;
+            }
+            // step 7: find actions
+            const actionFinder = await actions.Finder.loadStatic();
+            // step 8: execute the ActivityList
+            this.emit("start", { stepCount: links.length });
+            process.chdir(config.workspace.platformified());
+            const parResults = run.parallel(links, actionFinder, targets, config, this);
+            await Promise.all(parResults);
+            // step 9: cleanup
+            process.chdir(config.sourceDir.platformified());
+        }
+        finally {
+            process.chdir(originalDir);
+        }
+    }
+    on(name, handler) {
+        this.emitter.on(name, handler);
+        return this;
+    }
+}
+//# sourceMappingURL=static.js.map

package/dist/commands/unused.d.ts

@@ -0,0 +1,13 @@
+import { EventEmitter } from "events";
+import * as configuration from "../configuration/index.js";
+import * as events from "../events/index.js";
+import { Command } from "./command.js";
+export declare class Unused implements Command {
+    emitter: EventEmitter;
+    userConfig: configuration.APIData;
+    constructor(userConfig: configuration.APIData);
+    emit(name: events.Name, payload: events.Args): void;
+    execute(): Promise<void>;
+    on(name: events.Name, handler: events.Handler): this;
+}
+//# sourceMappingURL=unused.d.ts.map

package/dist/commands/unused.js

@@ -0,0 +1,43 @@
+import { EventEmitter } from "events";
+import * as actions from "../actions/index.js";
+import * as activities from "../activities/index.js";
+import * as configuration from "../configuration/index.js";
+import * as files from "../filesystem/index.js";
+import * as parsers from "../parsers/index.js";
+export class Unused {
+    constructor(userConfig) {
+        this.userConfig = userConfig;
+        this.emitter = new EventEmitter();
+    }
+    emit(name, payload) {
+        this.emitter.emit(name, payload);
+    }
+    async execute() {
+        // step 1: determine full configuration
+        const config = await configuration.addDefaults(this.userConfig);
+        // step 2: find files
+        const filenames = await files.getFileNames(config);
+        if (filenames.length === 0) {
+            this.emit("result", { message: "no Markdown files found", status: "warning" });
+            return;
+        }
+        // step 3: read and parse files
+        const ASTs = await parsers.markdown.parse(filenames, config.sourceDir);
+        // step 4: extract activities
+        const usedActivityNames = activities.extractDynamic(ASTs, config.regionMarker).map(activity => activity.actionName);
+        // step 5: find defined activities
+        const definedActivityNames = (await actions.Finder.load(config.sourceDir)).customActionNames();
+        // step 6: identify unused activities
+        const unusedActivityNames = definedActivityNames.filter(definedActivityName => !usedActivityNames.includes(definedActivityName));
+        // step 7: write results
+        this.emit("output", "Unused activities:");
+        for (const unusedActivityName of unusedActivityNames) {
+            this.emit("output", `- ${unusedActivityName}`);
+        }
+    }
+    on(name, handler) {
+        this.emitter.on(name, handler);
+        return this;
+    }
+}
+//# sourceMappingURL=unused.js.map

package/dist/configuration/data.d.ts

@@ -0,0 +1,46 @@
+import * as files from "../filesystem/index.js";
+import { Publications } from "./publications.js";
+/** configuration values used by the Text-Runner API */
+export type APIData = Partial<CompleteAPIData>;
+/** a full set of configuration values used by the Text-Runner API */
+export type CompleteAPIData = SharedValues & StringDirs;
+/** Configuration values used inside Text-Runner Engine */
+export type Data = AbsoluteDirs & SharedValues;
+interface AbsoluteDirs {
+    /** the root directory of the source code to test */
+    sourceDir: files.SourceDir;
+    /** the root directory of the workspace */
+    workspace: files.AbsoluteDirPath;
+}
+interface SharedValues {
+    /** the name of the default filename, set to '' if none is given */
+    defaultFile: string;
+    /** whether to empty the workspace before executing tests */
+    emptyWorkspace: boolean;
+    /** list of names or regexes of files to exclude */
+    exclude: string | string[];
+    /** glob of the files to test */
+    files: string;
+    /** link patterns to ignore */
+    ignoreLinkTargets: RegExp[];
+    /** whether to skip built-in tests that require a network connection */
+    online: boolean;
+    /** folder mappings */
+    publications: Publications;
+    /** the name of the attribute that denotes active regions */
+    regionMarker: string;
+    /** language in which to scaffold new steps */
+    scaffoldLanguage: "js" | "ts";
+    /** whether to display/emit skipped tests */
+    showSkipped: boolean;
+    /** whether to create the workspace in the system temp directory or locally */
+    systemTmp: boolean;
+}
+interface StringDirs {
+    /** the root directory of the source code to test */
+    sourceDir: string;
+    /** the root directory of the workspace */
+    workspace?: string;
+}
+export {};
+//# sourceMappingURL=data.d.ts.map

package/dist/configuration/data.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data.js.map

package/dist/configuration/defaults.d.ts

@@ -0,0 +1,5 @@
+import * as configuration from "./index.js";
+export declare function addDefaults(partial: configuration.APIData): Promise<configuration.Data>;
+/** provides the default configuration values to use when no values are provided via CLI or config file */
+export declare function defaults(): configuration.CompleteAPIData;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/configuration/defaults.js

@@ -0,0 +1,50 @@
+import * as path from "path";
+import * as tmp from "tmp-promise";
+import { UserError } from "../errors/user-error.js";
+import * as files from "../filesystem/index.js";
+import { Publications } from "./publications.js";
+export async function addDefaults(partial) {
+    const fullAPIData = defaults();
+    for (const [key, value] of Object.entries(partial)) {
+        if (value != null) {
+            // @ts-expect-error TypeScript is too stupid to realize that `key` has the correct type here
+            fullAPIData[key] = value;
+        }
+    }
+    return {
+        ...fullAPIData,
+        sourceDir: new files.SourceDir(fullAPIData.sourceDir),
+        workspace: await getWorkspacePath(fullAPIData)
+    };
+}
+/** provides the default configuration values to use when no values are provided via CLI or config file */
+export function defaults() {
+    return {
+        defaultFile: "",
+        emptyWorkspace: true,
+        exclude: [],
+        files: "**/*.md",
+        ignoreLinkTargets: [],
+        online: false,
+        publications: new Publications(),
+        regionMarker: "type",
+        scaffoldLanguage: "js",
+        showSkipped: false,
+        sourceDir: process.cwd(),
+        systemTmp: false,
+        workspace: "tmp"
+    };
+}
+async function getWorkspacePath(config) {
+    if (config.systemTmp === false) {
+        return new files.AbsoluteDirPath(path.join(config.sourceDir, config.workspace || "") || "");
+    }
+    else if (config.systemTmp === true) {
+        const tmpDir = await tmp.dir();
+        return new files.AbsoluteDirPath(path.join(tmpDir.path, config.workspace || ""));
+    }
+    else {
+        throw new UserError(`unknown 'systemTmp' setting: ${config.systemTmp}`, `Since version 5.0.0, the only valid settings for "systemTmp" are "true" and "false"`);
+    }
+}
+//# sourceMappingURL=defaults.js.map

package/dist/configuration/index.d.ts

@@ -0,0 +1,5 @@
+export type { APIData, CompleteAPIData, Data } from "./data.js";
+export { addDefaults, defaults } from "./defaults.js";
+export { Publication } from "./publication.js";
+export { Publications } from "./publications.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/configuration/index.js

@@ -0,0 +1,4 @@
+export { addDefaults, defaults } from "./defaults.js";
+export { Publication } from "./publication.js";
+export { Publications } from "./publications.js";
+//# sourceMappingURL=index.js.map

package/dist/configuration/publication.d.ts

@@ -0,0 +1,42 @@
+import * as files from "../filesystem/index.js";
+export interface PublicationConfig {
+    /** filesystem path of the src folder */
+    localPath: string;
+    /** which extension the Markdown files have when served as HTML */
+    publicExtension: string;
+    /** the corresponding URL path */
+    publicPath: string;
+}
+/**
+ * Publications map local folders (in the source code) to public URL paths.
+ * This is needed when verifying Markdown code that will be published as HTML somewhere,
+ * and the links in Markdown reference the public URLs of the Markdown pages.
+ */
+export declare class Publication implements PublicationConfig {
+    /** filesystem path of the src folder */
+    readonly localPath: string;
+    /** which extension the Markdown files have when served as HTML */
+    readonly publicExtension: string;
+    /** the corresponding URL path */
+    readonly publicPath: string;
+    constructor(args: {
+        localPath: string;
+        publicExtension: string;
+        publicPath: string;
+    });
+    /**
+     * Returns the public link under which the given file path would be published
+     * according to the rules of this publication
+     */
+    publish(localPath: files.FullPath): files.FullLink;
+    /** indicates whether this publication applies to the given file path */
+    publishes(localPath: files.FullPath): boolean;
+    /**
+     * provides the localPath for the given link
+     * mapped according to the rules of this publication.
+     */
+    resolve(link: files.FullLink, defaultFile: string): files.FullPath;
+    /** indicates whether this publication maps the given link */
+    resolves(link: files.FullLink): boolean;
+}
+//# sourceMappingURL=publication.d.ts.map

package/dist/configuration/publication.js

@@ -0,0 +1,51 @@
+import * as files from "../filesystem/index.js";
+import * as helpers from "../helpers/index.js";
+/**
+ * Publications map local folders (in the source code) to public URL paths.
+ * This is needed when verifying Markdown code that will be published as HTML somewhere,
+ * and the links in Markdown reference the public URLs of the Markdown pages.
+ */
+export class Publication {
+    constructor(args) {
+        this.localPath = helpers.addLeadingSlash(helpers.addTrailingSlash(args.localPath));
+        this.publicPath = helpers.addLeadingSlash(args.publicPath);
+        this.publicExtension = helpers.addLeadingDotUnlessEmpty(args.publicExtension);
+    }
+    /**
+     * Returns the public link under which the given file path would be published
+     * according to the rules of this publication
+     */
+    publish(localPath) {
+        const re = new RegExp("^" + this.localPath);
+        const linkPath = helpers.addLeadingSlash(localPath.unixified()).replace(re, this.publicPath);
+        const result = new files.FullLink(linkPath);
+        if (this.publicExtension == null) {
+            return result;
+        }
+        return result.withExtension(this.publicExtension);
+    }
+    /** indicates whether this publication applies to the given file path */
+    publishes(localPath) {
+        return helpers.addLeadingSlash(helpers.addTrailingSlash(localPath.unixified())).startsWith(this.localPath);
+    }
+    /**
+     * provides the localPath for the given link
+     * mapped according to the rules of this publication.
+     */
+    resolve(link, defaultFile) {
+        let result = link.rebase(this.publicPath, this.localPath);
+        result = result.withoutAnchor();
+        if (result.isLinkToDirectory()) {
+            result = result.append(new files.RelativeLink(defaultFile));
+        }
+        else if (result.hasExtension(this.publicExtension)) {
+            result = result.withExtension("md");
+        }
+        return new files.FullPath(result.value);
+    }
+    /** indicates whether this publication maps the given link */
+    resolves(link) {
+        return link.value.startsWith(this.publicPath);
+    }
+}
+//# sourceMappingURL=publication.js.map

package/dist/configuration/publications.d.ts

@@ -0,0 +1,9 @@
+import * as files from "../filesystem/index.js";
+import { Publication, PublicationConfig } from "./publication.js";
+export declare class Publications extends Array<Publication> {
+    static fromConfigs(configs?: PublicationConfig[]): Publications;
+    forFilePath(filePath: files.FullPath): Publication | undefined;
+    publicationForLink(link: files.FullLink): Publication | undefined;
+    sorted(): Publications;
+}
+//# sourceMappingURL=publications.d.ts.map

package/dist/configuration/publications.js

@@ -0,0 +1,25 @@
+import { Publication } from "./publication.js";
+export class Publications extends Array {
+    // Creates a new Publications instance based on the given JSON data
+    static fromConfigs(configs = []) {
+        const result = new Publications();
+        for (const config of configs) {
+            result.push(new Publication(config));
+        }
+        return result;
+    }
+    // Returns the publication that matches the given filepath
+    forFilePath(filePath) {
+        return this.find(publication => publication.publishes(filePath));
+    }
+    // Returns the publication that applies for the given link
+    publicationForLink(link) {
+        return this.find(publication => publication.resolves(link));
+    }
+    // Returns these publications, sorted by public path
+    sorted() {
+        const sorted = this.sort((a, b) => (a.publicPath > b.publicPath ? -1 : 1));
+        return Publications.fromConfigs(sorted);
+    }
+}
+//# sourceMappingURL=publications.js.map

package/dist/errors/error.d.ts

@@ -0,0 +1,2 @@
+export declare function errorMessage(err: unknown): string;
+//# sourceMappingURL=error.d.ts.map

package/dist/errors/error.js

@@ -0,0 +1,9 @@
+export function errorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    else {
+        return String(err);
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/errors/node-error.d.ts

@@ -0,0 +1,3 @@
+/** type guard that indicates errors of filesystem operations */
+export declare function isFsError(arg: unknown): arg is NodeJS.ErrnoException;
+//# sourceMappingURL=node-error.d.ts.map

package/dist/errors/node-error.js

@@ -0,0 +1,5 @@
+/** type guard that indicates errors of filesystem operations */
+export function isFsError(arg) {
+    return arg instanceof Error && "code" in arg;
+}
+//# sourceMappingURL=node-error.js.map

package/dist/errors/user-error.d.ts

@@ -0,0 +1,13 @@
+import * as files from "../filesystem/index.js";
+/**
+ * Represents a UserError that has not been printed via the formatter.
+ * This happens for user errors before the formatter could be instantiated
+ */
+export declare class UserError extends Error {
+    /** optional longer user-facing guidance on how to resolve the error */
+    readonly guidance: string;
+    readonly location: files.Location | undefined;
+    constructor(message: string, guidance: string, location?: files.Location);
+}
+export declare function isUserError(arg: unknown): arg is UserError;
+//# sourceMappingURL=user-error.d.ts.map

package/dist/errors/user-error.js

@@ -0,0 +1,16 @@
+/**
+ * Represents a UserError that has not been printed via the formatter.
+ * This happens for user errors before the formatter could be instantiated
+ */
+export class UserError extends Error {
+    constructor(message, guidance, location) {
+        super(message);
+        this.name = "UserError";
+        this.guidance = guidance;
+        this.location = location;
+    }
+}
+export function isUserError(arg) {
+    return arg instanceof Error && arg.name === "UserError";
+}
+//# sourceMappingURL=user-error.js.map

package/dist/events/index.d.ts

@@ -0,0 +1,49 @@
+import { Activity } from "../activities/index.js";
+export type Args = Failed | Skipped | Start | string | Success | Warning;
+/** signals a failed activity */
+export interface Failed {
+    readonly activity: Activity;
+    readonly error: Error;
+    readonly finalName: string;
+    /** captured output (via action.log) while executing the activity */
+    readonly output: string;
+    readonly status: "failed";
+}
+export type Handler = (arg: any) => void;
+/** defines the events that a command can emit. */
+export type Name = "finish" | "output" | "result" | "start";
+export interface Result {
+    readonly status: ResultStatus;
+}
+export type ResultStatus = "failed" | "skipped" | "success" | "warning";
+/** signals a skipped activity */
+export interface Skipped {
+    readonly activity: Activity;
+    readonly finalName: string;
+    readonly output: string;
+    readonly status: "skipped";
+}
+/** signals the start of a test suite */
+export interface Start {
+    readonly stepCount: number;
+}
+/** signals a successful activity */
+export interface Success {
+    readonly activity: Activity;
+    readonly finalName: string;
+    /** captured output (via action.log) while executing the activity */
+    readonly output: string;
+    readonly status: "success";
+}
+/** signals an activity succeeded but with warnings */
+export interface Warning {
+    readonly activity?: Activity;
+    readonly finalName?: string;
+    readonly message: string;
+    readonly status: "warning";
+}
+export declare function instanceOfFailed(event: Result): event is Failed;
+export declare function instanceOfSkipped(event: Result): event is Skipped;
+export declare function instanceOfSuccess(event: Result): event is Success;
+export declare function instanceOfWarning(event: Result): event is Warning;
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.js

@@ -0,0 +1,13 @@
+export function instanceOfFailed(event) {
+    return event.status === "failed";
+}
+export function instanceOfSkipped(event) {
+    return event.status === "skipped";
+}
+export function instanceOfSuccess(event) {
+    return event.status === "success";
+}
+export function instanceOfWarning(event) {
+    return event.status === "warning";
+}
+//# sourceMappingURL=index.js.map

package/dist/filesystem/absolute-dir.d.ts

@@ -0,0 +1,25 @@
+import * as files from "./index.js";
+/**
+ * represents an absolute path to a directory,
+ * i.e. path from filesystem root to the directory
+ */
+export declare class AbsoluteDirPath {
+    value: string;
+    constructor(value: string);
+    /** joins the given relative directory */
+    joinDir(other: files.RelativeDir): AbsoluteDirPath;
+    /** provides a path of this directory with the given path appended */
+    joinStr(...paths: string[]): string;
+    /** indicates whether this directory is the same as the given source dir */
+    matches(other: files.SourceDir): boolean;
+    /**
+     * Returns the path in the platform-specific format,
+     * i.e. using '\' on Windows and '/' everywhere else
+     */
+    platformified(): string;
+    relativeStr(other: string): string;
+    toFullDir(sourceDir: files.SourceDir): files.FullDir;
+    /** Returns this absolute path using forward slashes as path separators */
+    unixified(): string;
+}
+//# sourceMappingURL=absolute-dir.d.ts.map

package/dist/filesystem/absolute-dir.js

@@ -0,0 +1,42 @@
+import * as path from "path";
+import * as helpers from "../helpers/index.js";
+import * as files from "./index.js";
+/**
+ * represents an absolute path to a directory,
+ * i.e. path from filesystem root to the directory
+ */
+export class AbsoluteDirPath {
+    constructor(value) {
+        this.value = helpers.unixify(value);
+    }
+    /** joins the given relative directory */
+    joinDir(other) {
+        return new AbsoluteDirPath(this.joinStr(other.value));
+    }
+    /** provides a path of this directory with the given path appended */
+    joinStr(...paths) {
+        return path.join(this.platformified(), ...paths);
+    }
+    /** indicates whether this directory is the same as the given source dir */
+    matches(other) {
+        return this.unixified() === other.unixified();
+    }
+    /**
+     * Returns the path in the platform-specific format,
+     * i.e. using '\' on Windows and '/' everywhere else
+     */
+    platformified() {
+        return this.value.replace(/\//g, path.sep);
+    }
+    relativeStr(other) {
+        return path.relative(this.platformified(), other);
+    }
+    toFullDir(sourceDir) {
+        return new files.FullDir(path.relative(sourceDir.platformified(), this.platformified()));
+    }
+    /** Returns this absolute path using forward slashes as path separators */
+    unixified() {
+        return this.value;
+    }
+}
+//# sourceMappingURL=absolute-dir.js.map

package/dist/filesystem/absolute-file.d.ts

@@ -0,0 +1,18 @@
+import * as files from "./index.js";
+/** represents an absolute path to a file, i.e. from filesystem root to the file */
+export declare class AbsoluteFilePath {
+    value: string;
+    constructor(value: string);
+    /** provides the directory that contains this file */
+    directory(): files.AbsoluteDirPath;
+    /**
+     * provides this file path with platform specific path separators,
+     * i.e. '\' on Windows and '/' everywhere else
+     */
+    platformified(): string;
+    /** provides the relative path from the given directory to this file */
+    toFullFile(sourceDir: files.SourceDir): files.FullFilePath;
+    /** provides this file path with forward slashes as path separators */
+    unixified(): string;
+}
+//# sourceMappingURL=absolute-file.d.ts.map

package/dist/filesystem/absolute-file.js

@@ -0,0 +1,28 @@
+import * as path from "path";
+import * as files from "./index.js";
+/** represents an absolute path to a file, i.e. from filesystem root to the file */
+export class AbsoluteFilePath {
+    constructor(value) {
+        this.value = value;
+    }
+    /** provides the directory that contains this file */
+    directory() {
+        return new files.AbsoluteDirPath(path.dirname(this.value) + "/");
+    }
+    /**
+     * provides this file path with platform specific path separators,
+     * i.e. '\' on Windows and '/' everywhere else
+     */
+    platformified() {
+        return this.value.replace(/\//g, path.sep);
+    }
+    /** provides the relative path from the given directory to this file */
+    toFullFile(sourceDir) {
+        return new files.FullFilePath(path.relative(sourceDir.platformified(), this.platformified()));
+    }
+    /** provides this file path with forward slashes as path separators */
+    unixified() {
+        return this.value;
+    }
+}
+//# sourceMappingURL=absolute-file.js.map

package/dist/filesystem/full-dir.d.ts

@@ -0,0 +1,11 @@
+/** represents the full path to a directory inside the document base, i.e. from the document root */
+export declare class FullDir {
+    value: string;
+    constructor(value: string);
+    /**
+     * Returns the path in the platform-specific format,
+     * i.e. using '\' on Windows and '/' everywhere else
+     */
+    platformified(): string;
+}
+//# sourceMappingURL=full-dir.d.ts.map

package/dist/filesystem/full-dir.js

@@ -0,0 +1,15 @@
+import * as path from "path";
+/** represents the full path to a directory inside the document base, i.e. from the document root */
+export class FullDir {
+    constructor(value) {
+        this.value = value;
+    }
+    /**
+     * Returns the path in the platform-specific format,
+     * i.e. using '\' on Windows and '/' everywhere else
+     */
+    platformified() {
+        return this.value.replace(/\//g, path.sep);
+    }
+}
+//# sourceMappingURL=full-dir.js.map