@eagleoutice/flowr 1.3.11

package/cli/common/script.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processCommandLineArgs = exports.helpForOptions = void 0;
+/**
+ * The goal of this module is simply to streamline the creation of new scripts.
+ *
+ * @module
+ */
+const scripts_info_1 = require("./scripts-info");
+const command_line_usage_1 = __importDefault(require("command-line-usage"));
+const log_1 = require("../../util/log");
+const command_line_args_1 = __importDefault(require("command-line-args"));
+const statistics_1 = require("../../statistics");
+/**
+ * Automatically generates a uniform help from a given script (see {@link scripts}).
+ * Additionally, you can pass usage examples that may make use of the formatting instructions `{italic x}` and `{bold x}`.
+ */
+function helpForOptions(script, content) {
+    return (0, command_line_usage_1.default)([
+        {
+            header: scripts_info_1.scripts[script].description,
+            content: content.subtitle
+        },
+        {
+            header: 'Synopsis',
+            content: content.examples.map(e => `$ ${scripts_info_1.scripts[script].toolName} ${e}`)
+        },
+        {
+            header: 'Options',
+            optionList: scripts_info_1.scripts[script].options
+        }
+    ]);
+}
+exports.helpForOptions = helpForOptions;
+function processCommandLineArgs(script, requireAdditionally, help) {
+    const options = (0, command_line_args_1.default)(scripts_info_1.scripts[script].options);
+    if (options.help) {
+        console.log(helpForOptions(script, help));
+        process.exit(0);
+    }
+    else if (requireAdditionally.length > 0) {
+        const keys = new Set(Object.keys(options));
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- we know that they are not given if undefined
+        const missing = requireAdditionally.filter(k => !keys.has(k) || options[k] === undefined);
+        if (missing.length > 0) {
+            console.error((0, statistics_1.italic)(`Missing required arguments: ${missing.join(', ')}. Showing help.`));
+            console.log(helpForOptions(script, help));
+            process.exit(0);
+        }
+    }
+    log_1.log.updateSettings(l => l.settings.minLevel = options.verbose ? 1 /* LogLevel.Trace */ : 5 /* LogLevel.Error */);
+    if (options.verbose) {
+        log_1.log.info(`running with (debugging) options, ${JSON.stringify(options)}`);
+    }
+    return options;
+}
+exports.processCommandLineArgs = processCommandLineArgs;
+//# sourceMappingURL=script.js.map

package/cli/common/scripts-info.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This file contains the references to all scripts, as well as their explanations and arguments.
+ *
+ * @module
+ */
+import { MergeableRecord } from '../../util/objects';
+import { OptionDefinition } from 'command-line-usage';
+interface BaseScriptInformation extends MergeableRecord {
+    toolName: string;
+    target: string;
+    description: string;
+    usageExample: string;
+    options: OptionDefinition[];
+}
+export interface MasterScriptInformation extends BaseScriptInformation {
+    type: 'master script';
+}
+export interface HelperScriptInformation extends BaseScriptInformation {
+    type: 'helper script';
+    masterScripts: string[];
+}
+export type ScriptInformation = MasterScriptInformation | HelperScriptInformation;
+export declare const scripts: Record<"slicer" | "benchmark" | "summarizer" | "export-quads" | "stats" | "stats-helper" | "benchmark-helper", ScriptInformation>;
+export {};

package/cli/common/scripts-info.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scripts = void 0;
+const options_1 = require("./options");
+/**
+ * We hold `_scripts` internally, as the modifiable variant and export the readonly scripts
+ */
+const _scripts = {
+    'slicer': {
+        toolName: 'slicer',
+        target: 'slicer-app',
+        description: 'Static backwards executable slicer for R',
+        options: options_1.slicerOptions,
+        usageExample: 'slicer -c "12@product" test/testfiles/example.R',
+        type: 'master script',
+    },
+    'benchmark': {
+        toolName: 'benchmark',
+        target: 'benchmark-app',
+        description: 'Benchmark the static backwards slicer',
+        type: 'master script',
+        usageExample: 'benchmark "example-folder/"',
+        options: options_1.benchmarkOptions
+    },
+    'benchmark-helper': {
+        toolName: 'benchmark-single',
+        target: 'benchmark-helper-app',
+        description: 'Helper Script to Benchmark the Slicer',
+        usageExample: 'benchmark-single "example.R" --output "example.json"',
+        options: options_1.benchmarkHelperOptions,
+        type: 'helper script',
+        masterScripts: ['benchmark']
+    },
+    'summarizer': {
+        toolName: 'summarizer',
+        target: 'summarizer-app',
+        description: 'Summarize the results of the benchmark',
+        options: options_1.summarizerOptions,
+        usageExample: 'summarizer "benchmark.json"',
+        type: 'master script',
+    },
+    'export-quads': {
+        toolName: 'export-quads',
+        target: 'export-quads-app',
+        description: 'Export quads of the normalized AST of a given R code file',
+        usageExample: 'export-quads "example.R" --output "example.quads"',
+        options: options_1.exportQuadsOptions,
+        type: 'master script',
+    },
+    'stats': {
+        toolName: 'stats',
+        target: 'statistics-app',
+        description: 'Generate usage Statistics for R scripts',
+        options: options_1.statisticOptions,
+        usageExample: 'stats -i example.R --output-dir "output-folder/"',
+        type: 'master script',
+    },
+    'stats-helper': {
+        toolName: 'stats-helper',
+        target: 'statistics-helper-app',
+        description: 'Generate usage Statistics for a single R script (parallel helper for stats)',
+        options: options_1.statisticHelperOptions,
+        usageExample: 'stats-helper -i example.R --output-dir "output-folder/"',
+        type: 'helper script',
+        masterScripts: ['stats']
+    }
+};
+exports.scripts = _scripts;
+//# sourceMappingURL=scripts-info.js.map

package/cli/export-quads-app.d.ts

@@ -0,0 +1,7 @@
+export interface QuadsCliOptions {
+    verbose: boolean;
+    help: boolean;
+    input: string[];
+    limit: number;
+    output: string | undefined;
+}

package/cli/export-quads-app.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const r_bridge_1 = require("../r-bridge");
+const log_1 = require("../util/log");
+const quads_1 = require("../util/quads");
+const fs_1 = __importDefault(require("fs"));
+const files_1 = require("../util/files");
+const common_1 = require("./common");
+const options = (0, common_1.processCommandLineArgs)('export-quads', [], {
+    subtitle: 'Generate RDF N-Quads from the AST of a given R script',
+    examples: [
+        '{bold -i} {italic example.R} {bold --output} {italic "example.quads"}',
+        '{bold --help}'
+    ]
+});
+const shell = new r_bridge_1.RShell();
+shell.tryToInjectHomeLibPath();
+async function writeQuadForSingleFile(request, output) {
+    const normalized = await (0, r_bridge_1.retrieveNormalizedAstFromRCode)({
+        ...request,
+        ensurePackageInstalled: true
+    }, shell);
+    const serialized = (0, quads_1.serialize2quads)(normalized.ast, { context: request.content });
+    log_1.log.info(`Appending quads to ${output}`);
+    fs_1.default.appendFileSync(output, serialized);
+}
+async function getQuads() {
+    const output = options.output ?? 'out.quads';
+    let skipped = 0;
+    for await (const request of (0, files_1.allRFilesFrom)(options.input, options.limit)) {
+        try {
+            await writeQuadForSingleFile(request, output);
+        }
+        catch (e) {
+            log_1.log.error(`[Skipped] Error while processing ${request.content}: ${e.message} (${e.stack ?? ''})`);
+            skipped++;
+        }
+    }
+    console.log(`Skipped ${skipped} files`);
+    shell.close();
+}
+void getQuads();
+//# sourceMappingURL=export-quads-app.js.map

package/cli/repl/commands/cfg.d.ts

@@ -0,0 +1,3 @@
+import { ReplCommand } from './main';
+export declare const controlflowCommand: ReplCommand;
+export declare const controlflowStarCommand: ReplCommand;

package/cli/repl/commands/cfg.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.controlflowStarCommand = exports.controlflowCommand = void 0;
+const core_1 = require("../../../core");
+const r_bridge_1 = require("../../../r-bridge");
+const cfg_1 = require("../../../util/cfg");
+const mermaid_1 = require("../../../util/mermaid");
+async function controlflow(shell, remainingLine) {
+    return await new core_1.SteppingSlicer({
+        stepOfInterest: 'normalize',
+        shell,
+        request: (0, r_bridge_1.requestFromInput)(remainingLine.trim())
+    }).allRemainingSteps();
+}
+exports.controlflowCommand = {
+    description: 'Get mermaid code for the control-flow graph of R code, start with \'file://\' to indicate a file',
+    usageExample: ':controlflow',
+    aliases: ['cfg', 'cf'],
+    script: false,
+    fn: async (output, shell, remainingLine) => {
+        const result = await controlflow(shell, remainingLine);
+        const cfg = (0, cfg_1.extractCFG)(result.normalize);
+        output.stdout((0, mermaid_1.cfgToMermaid)(cfg, result.normalize));
+    }
+};
+exports.controlflowStarCommand = {
+    description: 'Get a mermaid url of the control-flow graph of R code, start with \'file://\' to indicate a file',
+    usageExample: ':controlflow',
+    aliases: ['cfg*', 'cf*'],
+    script: false,
+    fn: async (output, shell, remainingLine) => {
+        const result = await controlflow(shell, remainingLine);
+        const cfg = (0, cfg_1.extractCFG)(result.normalize);
+        output.stdout((0, mermaid_1.cfgToMermaidUrl)(cfg, result.normalize));
+    }
+};
+//# sourceMappingURL=cfg.js.map

package/cli/repl/commands/commands.d.ts

@@ -0,0 +1,11 @@
+import { ReplCommand } from './main';
+export declare const helpCommand: ReplCommand;
+/**
+ * The names of all commands including their aliases (but without the leading `:`)
+ */
+export declare const commandNames: string[];
+/**
+ * Get the command for a given command name or alias.
+ * @param command - The name of the command (without the leading `:`)
+ */
+export declare function getCommand(command: string): ReplCommand | undefined;

package/cli/repl/commands/commands.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommand = exports.commandNames = exports.helpCommand = void 0;
+const quit_1 = require("./quit");
+const common_1 = require("../../common");
+const execute_1 = require("../execute");
+const args_1 = require("../../../util/args");
+const prompt_1 = require("../prompt");
+const statistics_1 = require("../../../statistics");
+const version_1 = require("./version");
+const parse_1 = require("./parse");
+const assert_1 = require("../../../util/assert");
+const execute_2 = require("./execute");
+const normalize_1 = require("./normalize");
+const dataflow_1 = require("./dataflow");
+const cfg_1 = require("./cfg");
+function printHelpForScript(script, f) {
+    const base = `  ${(0, statistics_1.bold)(padCmd(':' + script[0]), f)}${script[1].description}`;
+    if (script[1].aliases.length === 0) {
+        return base;
+    }
+    const aliases = script[1].aliases;
+    return `${base} (alias${aliases.length > 1 ? 'es' : ''}: ${aliases.map(a => (0, statistics_1.bold)(':' + a, f)).join(', ')})`;
+}
+exports.helpCommand = {
+    description: 'Show help information',
+    script: false,
+    usageExample: ':help',
+    aliases: ['h', '?'],
+    fn: output => {
+        output.stdout(`
+You can always just enter R expressions which get evaluated right away:
+${prompt_1.rawPrompt} ${(0, statistics_1.bold)('1 + 1', output.formatter)}
+${(0, statistics_1.italic)('[1] 2', output.formatter)}
+
+Besides that, you can use the following commands. The scripts ${(0, statistics_1.italic)('can', output.formatter)} accept further arguments. There are the following basic commands:
+${Array.from(Object.entries(commands)).filter(([, { script }]) => !script).map(c => printHelpForScript(c, output.formatter)).join('\n')}
+
+Furthermore, you can directly call the following scripts which accept arguments. If you are unsure, try to add ${(0, statistics_1.italic)('--help', output.formatter)} after the command.
+${Array.from(Object.entries(commands)).filter(([, { script }]) => script).map(([command, { description }]) => `  ${(0, statistics_1.bold)(padCmd(':' + command), output.formatter)}${description}`).join('\n')}
+
+You can combine commands by separating them with a semicolon ${(0, statistics_1.bold)(';', output.formatter)}.
+`);
+    }
+};
+/**
+ * All commands that should be available in the REPL.
+ */
+const commands = {
+    'help': exports.helpCommand,
+    'quit': quit_1.quitCommand,
+    'version': version_1.versionCommand,
+    'execute': execute_2.executeCommand,
+    'parse': parse_1.parseCommand,
+    'normalize': normalize_1.normalizeCommand,
+    'normalize*': normalize_1.normalizeStarCommand,
+    'dataflow': dataflow_1.dataflowCommand,
+    'dataflow*': dataflow_1.dataflowStarCommand,
+    'controlflow': cfg_1.controlflowCommand,
+    'controlflow*': cfg_1.controlflowStarCommand
+};
+for (const [script, { target, description, type }] of Object.entries(common_1.scripts)) {
+    if (type === 'master script') {
+        commands[script] = {
+            description,
+            aliases: [],
+            script: true,
+            usageExample: `:${script} --help`,
+            fn: async (output, _s, remainingLine) => {
+                await (0, execute_1.waitOnScript)(`${__dirname}/../../${target}`, (0, args_1.splitAtEscapeSensitive)(remainingLine), stdio => (0, execute_1.stdioCaptureProcessor)(stdio, msg => output.stdout(msg), msg => output.stderr(msg)));
+            }
+        };
+    }
+}
+/**
+ * The names of all commands including their aliases (but without the leading `:`)
+ */
+exports.commandNames = [];
+// maps command names or aliases to the actual command name
+const commandMapping = {};
+for (const [command, { aliases }] of Object.entries(commands)) {
+    (0, assert_1.guard)(commandMapping[command] === undefined, `Command ${command} is already registered!`);
+    commandMapping[command] = command;
+    for (const alias of aliases) {
+        (0, assert_1.guard)(commandMapping[alias] === undefined, `Command (alias) ${alias} is already registered!`);
+        commandMapping[alias] = command;
+    }
+    exports.commandNames.push(command);
+    exports.commandNames.push(...aliases);
+}
+/**
+ * Get the command for a given command name or alias.
+ * @param command - The name of the command (without the leading `:`)
+ */
+function getCommand(command) {
+    return commands[commandMapping[command]];
+}
+exports.getCommand = getCommand;
+const longestKey = Array.from(Object.keys(commands), k => k.length).reduce((p, n) => Math.max(p, n), 0);
+function padCmd(string) {
+    return String(string).padEnd(longestKey + 2, ' ');
+}
+//# sourceMappingURL=commands.js.map

package/cli/repl/commands/dataflow.d.ts

@@ -0,0 +1,3 @@
+import { ReplCommand } from './main';
+export declare const dataflowCommand: ReplCommand;
+export declare const dataflowStarCommand: ReplCommand;

package/cli/repl/commands/dataflow.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataflowStarCommand = exports.dataflowCommand = void 0;
+const core_1 = require("../../../core");
+const r_bridge_1 = require("../../../r-bridge");
+const dfg_1 = require("../../../util/mermaid/dfg");
+async function dataflow(shell, remainingLine) {
+    return await new core_1.SteppingSlicer({
+        stepOfInterest: 'dataflow',
+        shell,
+        request: (0, r_bridge_1.requestFromInput)(remainingLine.trim())
+    }).allRemainingSteps();
+}
+exports.dataflowCommand = {
+    description: 'Get mermaid code for the dataflow graph of R code, start with \'file://\' to indicate a file',
+    usageExample: ':dataflow',
+    aliases: ['d', 'df'],
+    script: false,
+    fn: async (output, shell, remainingLine) => {
+        const result = await dataflow(shell, remainingLine);
+        output.stdout((0, dfg_1.graphToMermaid)(result.dataflow.graph, result.normalize.idMap, undefined, undefined, false));
+    }
+};
+exports.dataflowStarCommand = {
+    description: 'Get a mermaid url of the dataflow graph of R code, start with \'file://\' to indicate a file',
+    usageExample: ':dataflow*',
+    aliases: ['d*', 'df*'],
+    script: false,
+    fn: async (output, shell, remainingLine) => {
+        const result = await dataflow(shell, remainingLine);
+        output.stdout((0, dfg_1.graphToMermaidUrl)(result.dataflow.graph, result.normalize.idMap, false));
+    }
+};
+//# sourceMappingURL=dataflow.js.map

package/cli/repl/commands/execute.d.ts

@@ -0,0 +1,4 @@
+import { RShell } from '../../../r-bridge';
+import { ReplCommand, ReplOutput } from './main';
+export declare function executeRShellCommand(output: ReplOutput, shell: RShell, statement: string): Promise<void>;
+export declare const executeCommand: ReplCommand;

package/cli/repl/commands/execute.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeCommand = exports.executeRShellCommand = void 0;
+const statistics_1 = require("../../../statistics");
+async function executeRShellCommand(output, shell, statement) {
+    try {
+        const result = await shell.sendCommandWithOutput(statement, {
+            from: 'both',
+            automaticallyTrimOutput: true
+        });
+        output.stdout(`${(0, statistics_1.italic)(result.join('\n'), output.formatter)}\n`);
+    }
+    catch (e) {
+        output.stderr(`Error while executing '${statement}': ${e.message}`);
+    }
+}
+exports.executeRShellCommand = executeRShellCommand;
+exports.executeCommand = {
+    description: 'Execute the given code as R code (essentially similar to using now command)',
+    usageExample: ':execute',
+    aliases: ['e', 'r'],
+    script: false,
+    fn: async (output, shell, remainingLine) => {
+        await executeRShellCommand(output, shell, remainingLine);
+    }
+};
+//# sourceMappingURL=execute.js.map

package/cli/repl/commands/index.d.ts

@@ -0,0 +1,2 @@
+export * from './main';
+export * from './commands';

package/cli/repl/commands/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./main"), exports);
+__exportStar(require("./commands"), exports);
+//# sourceMappingURL=index.js.map

package/cli/repl/commands/main.d.ts

@@ -0,0 +1,39 @@
+import { RShell } from '../../../r-bridge';
+import { OutputFormatter } from '../../../statistics';
+/**
+ * Defines the main interface for output of the repl.
+ * This allows us to redirect it (e.g., in the case of a server connection or tests).
+ *
+ * The formatter allows to dynamically change the use of ansi escape sequences (see {@link OutputFormatter})
+ *
+ * @see standardReplOutput
+ */
+export interface ReplOutput {
+    formatter: OutputFormatter;
+    stdout(msg: string): void;
+    stderr(msg: string): void;
+}
+/**
+ * Default repl output that redirects everything to the stdout and stderror channels (linked to `console`).
+ * @see ReplOutput
+ */
+export declare const standardReplOutput: ReplOutput;
+/**
+ * Content of a single command in the repl.
+ * The command may execute an external script or simply call *flowR* functions.
+ */
+export interface ReplCommand {
+    /** Aliases of the command (without the leading colon), every alias must be unique (this is checked at runtime) */
+    aliases: string[];
+    /** A human-readable description of what the command does */
+    description: string;
+    /** Does the command invoke another script? this is mainly used to automatically generate two separate lists when asking for help */
+    script: boolean;
+    /** Example of how to use the command, for example `:slicer --help` */
+    usageExample: string;
+    /**
+     * Function to execute when the command is invoked, it must not write to the command line but instead use the output handler.
+     * Furthermore, it has to obey the formatter defined in the {@link ReplOutput}.
+     */
+    fn: (output: ReplOutput, shell: RShell, remainingLine: string) => Promise<void> | void;
+}

package/cli/repl/commands/main.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.standardReplOutput = void 0;
+const statistics_1 = require("../../../statistics");
+/**
+ * Default repl output that redirects everything to the stdout and stderror channels (linked to `console`).
+ * @see ReplOutput
+ */
+exports.standardReplOutput = {
+    formatter: statistics_1.formatter,
+    stdout: console.log,
+    stderr: console.error
+};
+//# sourceMappingURL=main.js.map

package/cli/repl/commands/normalize.d.ts

@@ -0,0 +1,3 @@
+import { ReplCommand } from './main';
+export declare const normalizeCommand: ReplCommand;
+export declare const normalizeStarCommand: ReplCommand;

package/cli/repl/commands/normalize.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeStarCommand = exports.normalizeCommand = void 0;
+const core_1 = require("../../../core");
+const r_bridge_1 = require("../../../r-bridge");
+const mermaid_1 = require("../../../util/mermaid");
+async function normalize(shell, remainingLine) {
+    return await new core_1.SteppingSlicer({
+        stepOfInterest: 'normalize',
+        shell,
+        request: (0, r_bridge_1.requestFromInput)(remainingLine.trim())
+    }).allRemainingSteps();
+}
+exports.normalizeCommand = {
+    description: 'Get mermaid code for the normalized AST of R code, start with \'file://\' to indicate a file',
+    usageExample: ':normalize',
+    aliases: ['n'],
+    script: false,
+    fn: async (output, shell, remainingLine) => {
+        const result = await normalize(shell, remainingLine);
+        output.stdout((0, mermaid_1.normalizedAstToMermaid)(result.normalize.ast));
+    }
+};
+exports.normalizeStarCommand = {
+    description: 'Get a mermaid url of the normalized AST of R code, start with \'file://\' to indicate a file',
+    usageExample: ':normalize',
+    aliases: ['n*'],
+    script: false,
+    fn: async (output, shell, remainingLine) => {
+        const result = await normalize(shell, remainingLine);
+        output.stdout((0, mermaid_1.normalizedAstToMermaidUrl)(result.normalize.ast));
+    }
+};
+//# sourceMappingURL=normalize.js.map

package/cli/repl/commands/parse.d.ts

@@ -0,0 +1,2 @@
+import { ReplCommand } from './main';
+export declare const parseCommand: ReplCommand;