@eagleoutice/flowr 1.5.2 → 2.0.1

package/benchmark/summarizer/summarizer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * This module is tasked with processing the results of the benchmarking (see {@link SlicerStats}).
+ * @module
+ */
+import type { UltimateSlicerStats } from './data';
+import type { CommonSummarizerConfiguration } from '../../util/summarizer';
+import { Summarizer } from '../../util/summarizer';
+export interface BenchmarkSummarizerConfiguration extends CommonSummarizerConfiguration {
+    /**
+     * If given, produce graph data output (e.g. for the benchmark visualization) to the given path
+     */
+    graphOutputPath?: string;
+    /**
+     * The input path to read from
+     */
+    inputPath: string;
+    /**
+     * Path for the intermediate results of the preparation phase
+     */
+    intermediateOutputPath: string;
+    /**
+     * Path for the final results of the summarization phase
+     */
+    outputPath: string;
+}
+export declare class BenchmarkSummarizer extends Summarizer<UltimateSlicerStats, BenchmarkSummarizerConfiguration> {
+    constructor(config: BenchmarkSummarizerConfiguration);
+    preparationPhase(): Promise<void>;
+    summarizePhase(): Promise<UltimateSlicerStats>;
+    private removeIfExists;
+}

package/benchmark/summarizer/summarizer.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BenchmarkSummarizer = void 0;
+const fs_1 = __importDefault(require("fs"));
+const input_1 = require("./first-phase/input");
+const process_1 = require("./second-phase/process");
+const graph_1 = require("./second-phase/graph");
+const path_1 = __importDefault(require("path"));
+const summarizer_1 = require("../../util/summarizer");
+const files_1 = require("../../util/files");
+const json_1 = require("../../util/json");
+const print_1 = require("../stats/print");
+class BenchmarkSummarizer extends summarizer_1.Summarizer {
+    constructor(config) {
+        super(config);
+    }
+    async preparationPhase() {
+        this.removeIfExists(`${this.config.intermediateOutputPath}.json`);
+        this.removeIfExists(this.config.intermediateOutputPath);
+        fs_1.default.mkdirSync(this.config.intermediateOutputPath);
+        const dirContent = fs_1.default.readdirSync(this.config.inputPath);
+        for (let i = 0; i < dirContent.length; i++) {
+            const filePath = path_1.default.join(this.config.inputPath, dirContent[i]);
+            const outputPath = path_1.default.join(this.config.intermediateOutputPath, dirContent[i]);
+            // generate measurements for each run
+            await (0, files_1.readLineByLine)(filePath, (line, lineNumber) => (0, input_1.processRunMeasurement)(line, i, lineNumber, `${outputPath}.log`, outputPath));
+            // generate combined measurements for the file
+            (0, input_1.processSummarizedFileMeasurement)(filePath, outputPath, `${this.config.intermediateOutputPath}.json`);
+        }
+        this.log('Done summarizing');
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await -- just to obey the structure
+    async summarizePhase() {
+        this.log(`Summarizing all summaries from ${this.config.inputPath}...`);
+        this.removeIfExists(this.config.outputPath);
+        const summaries = [];
+        (0, files_1.readLineByLineSync)(`${this.config.intermediateOutputPath}.json`, (l) => (0, process_1.processNextUltimateSummary)(l, summaries));
+        const ultimate = (0, process_1.summarizeAllUltimateStats)(summaries);
+        this.log(`Writing ultimate summary to ${this.config.outputPath}`);
+        fs_1.default.writeFileSync(this.config.outputPath, JSON.stringify(ultimate, json_1.jsonReplacer));
+        console.log((0, print_1.ultimateStats2String)(ultimate));
+        if (this.config.graphOutputPath) {
+            (0, graph_1.writeGraphOutput)(ultimate, this.config.graphOutputPath);
+        }
+        return ultimate;
+    }
+    removeIfExists(path) {
+        if (path && fs_1.default.existsSync(path)) {
+            this.log(`Removing existing ${path}`);
+            fs_1.default.rmSync(path, { recursive: true });
+        }
+    }
+}
+exports.BenchmarkSummarizer = BenchmarkSummarizer;
+//# sourceMappingURL=summarizer.js.map

package/cli/benchmark-app.d.ts

@@ -0,0 +1,10 @@
+export interface BenchmarkCliOptions {
+    verbose: boolean;
+    help: boolean;
+    input: string[];
+    output: string;
+    slice: string;
+    parallel: number;
+    limit?: number;
+    runs?: number;
+}

package/cli/benchmark-app.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const assert_1 = require("../util/assert");
+const files_1 = require("../util/files");
+const log_1 = require("../util/log");
+const parallel_1 = require("../util/parallel");
+const script_1 = require("./common/script");
+const options = (0, script_1.processCommandLineArgs)('benchmark', [], {
+    subtitle: 'Slice given files with additional benchmark information',
+    examples: [
+        '{italic example-folder/}',
+        '{bold --help}'
+    ]
+});
+if (options.input.length === 0) {
+    console.error('No input files given. Nothing to do. See \'--help\' if this is an error.');
+    process.exit(0);
+}
+(0, assert_1.guard)(options.slice === 'all' || options.slice === 'no', 'slice must be either all or no');
+(0, assert_1.guard)(options.runs === undefined || options.runs > 0, 'runs must be greater than zero');
+function removeIfExists(summarizedRaw) {
+    if (fs_1.default.existsSync(summarizedRaw)) {
+        console.log(`Removing existing ${summarizedRaw}`);
+        fs_1.default.rmSync(summarizedRaw, { recursive: true });
+    }
+}
+async function benchmark() {
+    removeIfExists(options.output);
+    fs_1.default.mkdirSync(options.output);
+    console.log(`Storing output in ${options.output}`);
+    console.log(`Using ${options.parallel} parallel executors`);
+    // we do not use the limit argument to be able to pick the limit randomly
+    const files = [];
+    for await (const file of (0, files_1.allRFilesFrom)(options.input)) {
+        files.push(file);
+    }
+    if (options.limit) {
+        log_1.log.info(`limiting to ${options.limit} files`);
+        // shuffle and limit
+        files.sort(() => Math.random() - 0.5);
+    }
+    const limit = options.limit ?? files.length;
+    const verboseAdd = options.verbose ? ['--verbose'] : [];
+    const args = files.map((f, i) => [
+        '--input', f.content,
+        '--file-id', `${i}`,
+        '--output', path_1.default.join(options.output, `${path_1.default.parse(f.content).name}.json`),
+        '--slice', options.slice, ...verboseAdd
+    ]);
+    const runs = options.runs ?? 1;
+    for (let i = 1; i <= runs; i++) {
+        console.log(`Run ${i} of ${runs}`);
+        const pool = new parallel_1.LimitedThreadPool(`${__dirname}/benchmark-helper-app`, 
+        // we reverse here "for looks", since the helper pops from the end, and we want file ids to be ascending :D
+        args.map(a => [...a, '--run-num', `${i}`]).reverse(), limit, options.parallel);
+        await pool.run();
+        const stats = pool.getStats();
+        console.log(`Run ${i} of ${runs}: Benchmarked ${stats.counter} files, skipped ${stats.skipped.length} files due to errors`);
+    }
+}
+void benchmark();
+//# sourceMappingURL=benchmark-app.js.map

package/cli/benchmark-helper-app.d.ts

@@ -0,0 +1,9 @@
+export interface SingleBenchmarkCliOptions {
+    verbose: boolean;
+    help: boolean;
+    input?: string;
+    'file-id'?: number;
+    'run-num'?: number;
+    slice: string;
+    output?: string;
+}

package/cli/benchmark-helper-app.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const log_1 = require("../util/log");
+const assert_1 = require("../util/assert");
+const json_1 = require("../util/json");
+const script_1 = require("./common/script");
+const slicer_1 = require("../benchmark/slicer");
+const all_variables_1 = require("../slicing/criterion/filters/all-variables");
+const options = (0, script_1.processCommandLineArgs)('benchmark-helper', [], {
+    subtitle: 'Will slice for all possible variables, signal by exit code if slicing was successful, and can be run standalone',
+    examples: [
+        '{italic example-file.R} --output {italic output.json}',
+        '{bold --help}'
+    ]
+});
+if (options.verbose) {
+    log_1.log.error('running with *verbose* setting - do not use for final benchmark', options);
+}
+(0, assert_1.guard)(options.slice === 'all' || options.slice === 'no', 'slice must be either all or no');
+async function benchmark() {
+    // we do not use the limit argument to be able to pick the limit randomly
+    (0, assert_1.guard)(options.input !== undefined, 'No input file given');
+    (0, assert_1.guard)(options.output !== undefined, 'No output file given');
+    (0, assert_1.guard)((options['file-id'] === undefined) === (options['run-num'] === undefined), 'When giving a file-id or run-num, both have to be given');
+    // prefix for printing to console, includes file id and run number if present
+    const prefix = `[${options.input}${options['file-id'] !== undefined ? ` (file ${options['file-id']}, run ${options['run-num']})` : ''}]`;
+    console.log(`${prefix} Appending output to ${options.output}`);
+    // ensure the file exists
+    const fileStat = fs_1.default.statSync(options.input);
+    (0, assert_1.guard)(fileStat.isFile(), `File ${options.input} does not exist or is no file`);
+    const request = { request: 'file', content: options.input };
+    const slicer = new slicer_1.BenchmarkSlicer();
+    try {
+        await slicer.init(request);
+        // ${escape}1F${escape}1G${escape}2K for line reset
+        if (options.slice === 'all') {
+            const count = await slicer.sliceForAll(all_variables_1.DefaultAllVariablesFilter, (i, total, arr) => console.log(`${prefix} Slicing ${i + 1}/${total} [${JSON.stringify(arr[i])}]`));
+            console.log(`${prefix} Completed Slicing`);
+            (0, assert_1.guard)(count > 0, `No possible slices found for ${options.input}, skipping in count`);
+        }
+        else {
+            console.log(`${prefix} Skipping Slicing due to --slice=${options.slice}`);
+        }
+        const { stats } = slicer.finish();
+        const output = {
+            filename: options.input,
+            'file-id': options['file-id'],
+            'run-num': options['run-num'],
+            stats
+        };
+        // append line by line
+        fs_1.default.appendFileSync(options.output, `${JSON.stringify(output, json_1.jsonReplacer)}\n`);
+    }
+    catch (e) {
+        if (e instanceof Error) {
+            if (!e.message.includes('unable to parse R')) {
+                console.log(`${prefix} Non R-Side error : ${e.message}`);
+            }
+        }
+        slicer.ensureSessionClosed(); // ensure finish
+        throw e;
+    }
+}
+void benchmark();
+//# sourceMappingURL=benchmark-helper-app.js.map

package/cli/common/features.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureKey } from '../../statistics/features/feature';
+export declare function validateFeatures(features: (string[] | ['all'] | FeatureKey[])): Set<FeatureKey>;
+export declare function retrieveArchiveName(p: string): string;

package/cli/common/features.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retrieveArchiveName = exports.validateFeatures = void 0;
+const path_1 = __importDefault(require("path"));
+const feature_1 = require("../../statistics/features/feature");
+function validateFeatures(features) {
+    for (const feature of features) {
+        if (feature === 'all') {
+            if (features.length > 1) {
+                console.error(`Feature "all" must be the only feature given, got ${features.join(', ')}`);
+                process.exit(1);
+            }
+        }
+        else if (!feature_1.allFeatureNames.has(feature)) {
+            console.error(`Feature ${feature} is unknown, supported are ${[...feature_1.allFeatureNames].join(', ')} or "all"`);
+            process.exit(1);
+        }
+    }
+    return features[0] === 'all' ? feature_1.allFeatureNames : new Set(features);
+}
+exports.validateFeatures = validateFeatures;
+function retrieveArchiveName(p) {
+    const basepath = path_1.default.normalize(p);
+    return `${basepath.endsWith(path_1.default.sep) ? basepath.substring(0, basepath.length - 1) : basepath}.tar.gz`;
+}
+exports.retrieveArchiveName = retrieveArchiveName;
+//# sourceMappingURL=features.js.map

package/cli/common/options.d.ts

@@ -0,0 +1,20 @@
+import type { OptionDefinition } from 'command-line-usage';
+/**
+ * This interface describes options, that every script *must* provide.
+ */
+export interface CommonOptions {
+    /** Enables the most verbose logging option available. */
+    verbose: boolean;
+    /**
+     * Shows the respective help including usage examples,
+     * see {@link processCommandLineArgs} or {@link helpForOptions} for more information.
+     */
+    help: boolean;
+}
+export declare const benchmarkOptions: OptionDefinition[];
+export declare const benchmarkHelperOptions: OptionDefinition[];
+export declare const exportQuadsOptions: OptionDefinition[];
+export declare const slicerOptions: OptionDefinition[];
+export declare const statisticOptions: OptionDefinition[];
+export declare const statisticHelperOptions: OptionDefinition[];
+export declare const summarizerOptions: OptionDefinition[];

package/cli/common/options.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizerOptions = exports.statisticHelperOptions = exports.statisticOptions = exports.slicerOptions = exports.exportQuadsOptions = exports.benchmarkHelperOptions = exports.benchmarkOptions = void 0;
+const os_1 = __importDefault(require("os"));
+const time_1 = require("../../util/time");
+const feature_1 = require("../../statistics/features/feature");
+/**
+ * This string contains a string representation of the loading time of this module.
+ */
+const StartTimeString = (0, time_1.date2string)(new Date());
+exports.benchmarkOptions = [
+    { name: 'verbose', alias: 'v', type: Boolean, description: 'Run with verbose logging [do not use for the real benchmark as this affects the time measurements, but only to find errors]' },
+    { name: 'help', alias: 'h', type: Boolean, description: 'Print this usage guide' },
+    { name: 'limit', alias: 'l', type: Number, description: 'Limit the number of files to process (if given, this will choose these files randomly and add the chosen names to the output' },
+    { name: 'runs', alias: 'r', type: Number, description: 'The amount of benchmark runs that should be done, out of which an average will be calculated' },
+    { name: 'input', alias: 'i', type: String, description: 'Pass a folder or file as src to read from', multiple: true, defaultOption: true, defaultValue: [], typeLabel: '{underline files/folders}' },
+    { name: 'parallel', alias: 'p', type: String, description: 'Number of parallel executors (defaults to {italic max(cpu.count-1, 1)})', defaultValue: Math.max(os_1.default.cpus().length - 1, 1), typeLabel: '{underline number}' },
+    { name: 'slice', alias: 's', type: String, description: 'Automatically slice for *all* variables (default) or *no* slicing and only parsing/dataflow construction', defaultValue: 'all', typeLabel: '{underline all/no}' },
+    { name: 'output', alias: 'o', type: String, description: `Directory to write all the measurements to in a per-file-basis (defaults to {italic benchmark-${StartTimeString}})`, defaultValue: `benchmark-${StartTimeString}`, typeLabel: '{underline file}' }
+];
+exports.benchmarkHelperOptions = [
+    { name: 'verbose', alias: 'v', type: Boolean, description: 'Run with verbose logging [do not use for the real benchmark as this affects the time measurements, but only to find errors]' },
+    { name: 'help', alias: 'h', type: Boolean, description: 'Print this usage guide' },
+    { name: 'input', alias: 'i', type: String, description: 'Pass a single file as src to read from', multiple: false, defaultOption: true, typeLabel: '{underline file}' },
+    { name: 'file-id', alias: 'd', type: Number, description: 'A numeric file id that can be used to match an input and run-num to a file' },
+    { name: 'run-num', alias: 'r', type: Number, description: 'The n-th time that the file with the given file-id is being benchmarked' },
+    { name: 'slice', alias: 's', type: String, description: 'Automatically slice for *all* variables (default) or *no* slicing and only parsing/dataflow construction', defaultValue: 'all', typeLabel: '{underline all/no}' },
+    { name: 'output', alias: 'o', type: String, description: 'File to write the measurements to (appends a single line in JSON format)', typeLabel: '{underline file}' },
+];
+exports.exportQuadsOptions = [
+    { name: 'verbose', alias: 'v', type: Boolean, description: 'Run with verbose logging' },
+    { name: 'help', alias: 'h', type: Boolean, description: 'Print this usage guide' },
+    { name: 'input', alias: 'i', type: String, description: 'Pass a folder or file as src to read from', multiple: true, defaultOption: true, defaultValue: [], typeLabel: '{underline files/folders}' },
+    { name: 'limit', alias: 'l', type: Number, description: 'Limit the number of files to process' },
+    { name: 'output', alias: 'o', type: String, description: 'File to write all the generated quads to (defaults to {italic out.quads})', typeLabel: '{underline file}' },
+];
+exports.slicerOptions = [
+    { name: 'verbose', alias: 'v', type: Boolean, description: 'Run with verbose logging' },
+    { name: 'help', alias: 'h', type: Boolean, description: 'Print this usage guide' },
+    { name: 'input', alias: 'i', type: String, description: '(Required) Pass a single file to slice', multiple: false, defaultOption: true, typeLabel: '{underline files}' },
+    { name: 'input-is-text', alias: 'r', type: Boolean, description: 'Indicate, that the input is *not* a file, but R code to directly consume' },
+    { name: 'diff', alias: 'd', type: Boolean, description: 'This requires ansi-output and only works if the api option is not set. It visualizes the slice as a diff.' },
+    { name: 'criterion', alias: 'c', type: String, description: '(Required) Slicing criterion either in the form {underline line:col} or {underline line@variable}, multiple can be separated by \'{bold ;}\'. If you do not want to slice but only process the file, pass an empty string.', multiple: false },
+    { name: 'stats', alias: 's', type: Boolean, description: 'Print stats and write them to {italic <output>.stats} (runtimes etc.)', multiple: false },
+    { name: 'output', alias: 'o', type: String, description: 'File to write all the generated quads to (defaults to the commandline)', typeLabel: '{underline file}' },
+    { name: 'api', type: Boolean, description: 'Instead of human-readable output, dump a lot of json with the results of all intermediate steps.' },
+];
+const featureNameList = [...feature_1.allFeatureNames].map(s => `"${s}"`).join(', ');
+exports.statisticOptions = [
+    { name: 'verbose', alias: 'v', type: Boolean, description: 'Run with verbose logging' },
+    { name: 'help', alias: 'h', type: Boolean, description: 'Print this usage guide' },
+    { name: 'limit', alias: 'l', type: Number, description: 'Limit the number of files to process' },
+    { name: 'input', alias: 'i', type: String, description: 'Pass a folder or file as src to read from', multiple: true, defaultOption: true, defaultValue: [], typeLabel: '{underline files/folders}' },
+    { name: 'output-dir', alias: 'o', type: String, description: 'Folder to write the output to', defaultValue: `${process.cwd()}/statistics-out/${(0, time_1.date2string)(new Date())}`, typeLabel: '{underline folder}' },
+    { name: 'dump-json', type: Boolean, description: 'Write JSON output during the extraction', typeLabel: '{underline folder}' },
+    { name: 'no-ansi', type: Boolean, description: 'Disable ansi-escape-sequences in the output. Useful, if you want to redirect the output to a file.' },
+    { name: 'parallel', alias: 'p', type: String, description: 'Number of parallel executors (defaults to {italic max(cpu.count-1, 1)})', defaultValue: Math.max(os_1.default.cpus().length - 1, 1), typeLabel: '{underline number}' },
+    { name: 'features', type: String, description: `Features to track, supported are "all" or ${featureNameList}`, multiple: true, defaultValue: 'all', typeLabel: '{underline names}' },
+];
+exports.statisticHelperOptions = [
+    { name: 'verbose', alias: 'v', type: Boolean, description: 'Run with verbose logging' },
+    { name: 'help', alias: 'h', type: Boolean, description: 'Print this usage guide' },
+    { name: 'input', alias: 'i', type: String, description: 'Pass single file as src to read from', multiple: false, defaultOption: true, typeLabel: '{underline file}' },
+    { name: 'output-dir', alias: 'o', type: String, description: 'Folder to write the output to', typeLabel: '{underline folder}' },
+    { name: 'root-dir', type: String, description: 'Root dir for the statistics files', defaultValue: '' },
+    { name: 'compress', type: Boolean, description: 'Compress the output folder to a single file', defaultValue: false },
+    { name: 'dump-json', type: Boolean, description: 'Write JSON output during the extraction', typeLabel: '{underline folder}' },
+    { name: 'no-ansi', type: Boolean, description: 'Disable ansi-escape-sequences in the output. Useful, if you want to redirect the output to a file.' },
+    { name: 'features', type: String, description: `Features to track, supported are "all" or ${featureNameList}`, multiple: true, defaultValue: 'all', typeLabel: '{underline names}' },
+];
+exports.summarizerOptions = [
+    { name: 'verbose', alias: 'v', type: Boolean, description: 'Run with verbose logging' },
+    { name: 'help', alias: 'h', type: Boolean, description: 'Print this usage guide' },
+    { name: 'type', alias: 't', type: String, description: 'Manually specify if you want to post-process benchmark results, statistics, or compressed statistics (defaults to auto).', defaultValue: 'auto' },
+    { name: 'graph', alias: 'g', type: Boolean, description: 'Produce data to be used for visualizing benchmarks over time' },
+    { name: 'categorize', type: Boolean, description: 'Categorize the results (e.g., "test", "example", ...)', defaultValue: false },
+    { name: 'project-skip', type: Number, description: 'Skip the first n folders to find the location of projects', defaultValue: 0 },
+    { name: 'ultimate-only', alias: 'u', type: Boolean, description: 'Only perform the second summary-stage, with this, the input is used to find the summary-output.' },
+    { name: 'input', alias: 'i', type: String, description: 'The {italic output} produced by the benchmark, the statistics, ...', defaultOption: true, multiple: false, typeLabel: '{underline file.json/output}' },
+    { name: 'output', alias: 'o', type: String, description: 'Basename of the summaries (defaults to {italic <input>-summary})', typeLabel: '{underline file}' },
+];
+//# sourceMappingURL=options.js.map

package/cli/common/script.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The goal of this module is simply to streamline the creation of new scripts.
+ *
+ * @module
+ */
+import { scripts } from './scripts-info';
+import type { CommonOptions } from './options';
+/**
+ * Just a helping data structure to allow the user to provide example usages of the respective script.
+ * The subtitle will be displayed next to the title.
+ */
+export interface HelpContent {
+    subtitle: string;
+    examples: string[];
+}
+/**
+ * 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}`.
+ */
+export declare function helpForOptions(script: keyof typeof scripts, content: HelpContent): string;
+export declare function processCommandLineArgs<T extends CommonOptions>(script: keyof typeof scripts, requireAdditionally: (keyof T)[], help: HelpContent): T;

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 command_line_args_1 = __importDefault(require("command-line-args"));
+const ansi_1 = require("../../util/ansi");
+const log_1 = require("../../util/log");
+/**
+ * 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, ansi_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,25 @@
+/**
+ * This file contains the references to all scripts, as well as their explanations and arguments.
+ *
+ * @module
+ */
+import type { OptionDefinition } from 'command-line-usage';
+import type { MergeableRecord } from '../../util/objects';
+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" | "stats" | "summarizer" | "export-quads" | "stats-helper" | "benchmark-helper", ScriptInformation>;
+export declare function getValidOptionsForCompletion(options: readonly OptionDefinition[], prevArgs: readonly string[]): string[];
+export {};

package/cli/common/scripts-info.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValidOptionsForCompletion = exports.scripts = void 0;
+const options_1 = require("./options");
+const commands_1 = require("../repl/commands/commands");
+/**
+ * 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;
+function getValidOptionsForCompletion(options, prevArgs) {
+    return options.filter(o => canAddOption(o, prevArgs)).flatMap(o => {
+        const args = [(0, commands_1.asOptionName)(o.name)];
+        if (o.alias) {
+            args.push((0, commands_1.asOptionName)(o.alias));
+        }
+        return args;
+    });
+}
+exports.getValidOptionsForCompletion = getValidOptionsForCompletion;
+function canAddOption(option, prevArgs) {
+    return option.multiple || !prevArgs.includes((0, commands_1.asOptionName)(option.name)) && (!option.alias || !prevArgs.includes((0, commands_1.asOptionName)(option.alias)));
+}
+//# 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,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const quads_1 = require("../util/quads");
+const log_1 = require("../util/log");
+const files_1 = require("../util/files");
+const script_1 = require("./common/script");
+const shell_1 = require("../r-bridge/shell");
+const retriever_1 = require("../r-bridge/retriever");
+const options = (0, script_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 shell_1.RShell();
+async function writeQuadForSingleFile(request, output) {
+    const normalized = await (0, retriever_1.retrieveNormalizedAstFromRCode)(request, 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