@eagleoutice/flowr-dev/project/plugins/flowr-analyzer-plugin.js

Static Dataflow Analyzer and Program Slicer for the R Programming Language

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.FlowrAnalyzerPlugin = exports.PluginType = void 0;
const log_1 = require("../../util/log");
/**
 * Based on *when* and *what-for* the plugin is applied during the analysis,
 * plugins are categorized into different types.
 *
 * Consult this diagram for an overview of orders and (implicit or explicit) dependencies:
 *
 * ```text
 * ┌───────────┐   ┌───────────────────┐   ┌─────────────┐   ┌───────────────┐   ┌───────┐
 * │           │   │                   │   │             │   │               │   │       │
 * │ *Builder* ├──▶│ Project Discovery ├──▶│ File Loader ├──▶│ Dependencies  ├──▶│ *DFA* │
 * │           │   │  (if necessary)   │   │             │   │   (static)    │   │       │
 * └───────────┘   └───────────────────┘   └──────┬──────┘   └───────────────┘   └────┬──┘
 *                                                │                                  ▲│
 *                                                │          ┌───────────────┐       ││
 *                                                │          │               │       ││ on-demand
 *                                                └─────────▶│ Loading Order ├───────┘│
 *                                                           │               │        │  ┌───────────┐
 *                                                           └───────────────┘        └─▶│    Gas    │
 *                                                                                       └───────────┘
 *```
 *
 */
var PluginType;
(function (PluginType) {
    /**
     * Plugins that are applied right after the builder has been created and before any analysis is done.
     * @see {@link FlowrAnalyzerPackageVersionsPlugin} - for the base class to implement such a plugin.
     */
    PluginType["DependencyIdentification"] = "package-versions";
    /**
     * Plugins that are used to determine the order in which files are loaded and analyzed.
     * @see {@link FlowrAnalyzerLoadingOrderPlugin} - for the base class to implement such a plugin.
     */
    PluginType["LoadingOrder"] = "loading-order";
    /**
     * Plugins that are applied to discover the project structure, files, and folders to analyze.
     * @see {@link FlowrAnalyzerProjectDiscoveryPlugin} - for the base class to implement such a plugin.
     */
    PluginType["ProjectDiscovery"] = "project-discovery";
    /**
     * Plugins that are applied to load and parse files.
     * @see {@link FlowrAnalyzerFilePlugin} - for the base class to implement such a plugin.
     */
    PluginType["FileLoad"] = "file-load";
    /**
     * Plugins that are queried on-demand during analysis to report the current resource-usage pressure level.
     * Multiple Gas plugins are combined by taking the maximum level returned.
     * @see {@link FlowrAnalyzerGasPlugin} - for the base class to implement such a plugin.
     */
    PluginType["Gas"] = "gas";
})(PluginType || (exports.PluginType = PluginType = {}));
const generalPluginLog = log_1.log.getSubLogger({ name: 'plugins' });
/**
 * The base class every plugin to be used with the {@link FlowrAnalyzer} must extend.
 * **Please do not create plugins directly based on this class, but use the classes referenced alongside the {@link PluginType} values!**
 * For example, if you want to create a plugin that determines the loading order of files, extend {@link FlowrAnalyzerLoadingOrderPlugin} instead.
 * These classes also provide sensible overrides of {@link FlowrAnalyzerPlugin.defaultPlugin} to be used when no plugin of this type is registered or triggered.
 *
 * For a collection of default plugins, see {@link FlowrDefaultPlugins}.
 */
class FlowrAnalyzerPlugin {
    /**
     * Returns a default/dummy implementation to be used when no plugin of this type is registered or triggered.
     */
    static defaultPlugin() {
        throw new Error('This is to be implemented by every Plugin Layer');
    }
    /**
     * Run the plugin with the given context and arguments.
     */
    processor(context, args) {
        const now = Date.now();
        try {
            // record activation before running: many plugins contribute by mutating the context and return `void`, so
            // a return value is not a reliable signal -- a plugin activated if its processor ran for this analysis
            if (context.config.repl.showPlugins) {
                context.activatedPlugins.add(this.constructor.name);
            }
            const result = this.process(context, args);
            const duration = Date.now() - now;
            (0, log_1.expensiveTrace)(generalPluginLog, () => `Plugin ${this.name} (v${this.version.format()}, ${this.type}) executed in ${duration}ms.`);
            return result;
        }
        catch (error) {
            const duration = Date.now() - now;
            generalPluginLog.error(`Plugin ${this.name} (v${this.version.format()}, ${this.type}) failed after ${duration}ms. Error: ${error.message}`);
            throw error;
        }
    }
}
exports.FlowrAnalyzerPlugin = FlowrAnalyzerPlugin;
//# sourceMappingURL=flowr-analyzer-plugin.js.map