@eagleoutice/flowr 1.3.11

package/benchmark/stats/print.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ultimateStats2String = exports.stats2string = void 0;
+/**
+ * This module is tasked with processing the results of the benchmarking (see {@link SummarizedSlicerStats}).
+ * @module
+ */
+const assert_1 = require("../../util/assert");
+const padSize = 15;
+function pad(string) {
+    return String(string).padStart(padSize, ' ');
+}
+function divWithRest(dividend, divisor) {
+    return [dividend / divisor, dividend % divisor];
+}
+function formatNanoseconds(nanoseconds) {
+    if (nanoseconds < 0) {
+        return '??';
+    }
+    const [seconds, rest] = divWithRest(typeof nanoseconds === 'number' ? BigInt(Math.round(nanoseconds)) : nanoseconds, BigInt(1e9));
+    const [milliseconds, remainingNanoseconds] = divWithRest(rest, BigInt(1e6));
+    const secondsStr = seconds > 0 ? `${String(seconds).padStart(2, '0')}.` : '';
+    const millisecondsStr = seconds > 0 ? `${String(milliseconds).padStart(3, '0')}:` : `${String(milliseconds)}:`;
+    const nanoStr = String(remainingNanoseconds).padEnd(3, '0').substring(0, 3);
+    const unit = seconds === 0n ? 'ms' : ' s'; /* space for padding */
+    return pad(`${secondsStr}${millisecondsStr}${nanoStr}${unit}`);
+}
+function print(measurements, key) {
+    const time = measurements.get(key);
+    (0, assert_1.guard)(time !== undefined, `Measurement for ${JSON.stringify(key)} not found`);
+    return formatNanoseconds(time);
+}
+function formatSummarizedTimeMeasure(measure) {
+    if (measure === undefined) {
+        return '??';
+    }
+    return `${formatNanoseconds(measure.min)} - ${formatNanoseconds(measure.max)} (median: ${formatNanoseconds(measure.median)}, mean: ${formatNanoseconds(measure.mean)}, std: ${formatNanoseconds(measure.std)})`;
+}
+function roundTo(num, digits = 4) {
+    const factor = Math.pow(10, digits);
+    return Math.round(num * factor) / factor;
+}
+function asPercentage(num) {
+    if (isNaN(num)) {
+        return '??%';
+    }
+    return pad(`${roundTo(num * 100, 3)}%`);
+}
+function asFloat(num) {
+    return pad(roundTo(num));
+}
+function formatSummarizedMeasure(measure, fmt = asFloat) {
+    if (measure === undefined) {
+        return '??';
+    }
+    return `${fmt(measure.min)} - ${fmt(measure.max)} (median: ${fmt(measure.median)}, mean: ${fmt(measure.mean)}, std: ${fmt(measure.std)})`;
+}
+function printSummarizedMeasurements(stats, key) {
+    const measure = stats.measurements.get(key);
+    (0, assert_1.guard)(measure !== undefined, `Measurement for ${JSON.stringify(key)} not found`);
+    return formatSummarizedTimeMeasure(measure);
+}
+function printCountSummarizedMeasurements(stats) {
+    const range = `${stats.min} - ${stats.max}`.padStart(padSize, ' ');
+    return `${range} (median: ${stats.median}, mean: ${stats.mean}, std: ${stats.std})`;
+}
+/**
+ * Converts the given stats to a human-readable string.
+ * You may have to {@link summarizeSlicerStats | summarize} the stats first.
+ */
+function stats2string(stats) {
+    let result = `
+Request: ${JSON.stringify(stats.request)}
+Shell init time:              ${print(stats.commonMeasurements, 'initialize R session')}
+Retrieval of token map:       ${print(stats.commonMeasurements, 'retrieve token map')}
+AST retrieval:                ${print(stats.commonMeasurements, 'retrieve AST from R code')}
+AST normalization:            ${print(stats.commonMeasurements, 'normalize R AST')}
+Dataflow creation:            ${print(stats.commonMeasurements, 'produce dataflow information')}
+
+Slicing summary for ${stats.perSliceMeasurements.numberOfSlices} slice${stats.perSliceMeasurements.numberOfSlices !== 1 ? 's' : ''}:`;
+    if (stats.perSliceMeasurements.numberOfSlices > 0) {
+        result += `
+  Total:                      ${printSummarizedMeasurements(stats.perSliceMeasurements, 'total')}
+  Slice creation:             ${printSummarizedMeasurements(stats.perSliceMeasurements, 'static slicing')}
+  Reconstruction:             ${printSummarizedMeasurements(stats.perSliceMeasurements, 'reconstruct code')}
+  Used Slice Criteria Sizes:  ${printCountSummarizedMeasurements(stats.perSliceMeasurements.sliceCriteriaSizes)}
+  Result Slice Sizes:   
+    Number of lines:                     ${printCountSummarizedMeasurements(stats.perSliceMeasurements.sliceSize.lines)}
+    Number of characters:                ${printCountSummarizedMeasurements(stats.perSliceMeasurements.sliceSize.characters)}
+    Number of non whitespace characters: ${printCountSummarizedMeasurements(stats.perSliceMeasurements.sliceSize.nonWhitespaceCharacters)}
+    Number of auto selected:             ${printCountSummarizedMeasurements(stats.perSliceMeasurements.sliceSize.autoSelected)}
+    Number of R tokens:                  ${printCountSummarizedMeasurements(stats.perSliceMeasurements.sliceSize.tokens)}
+    Normalized R tokens:                 ${printCountSummarizedMeasurements(stats.perSliceMeasurements.sliceSize.normalizedTokens)}
+    Number of dataflow nodes:            ${printCountSummarizedMeasurements(stats.perSliceMeasurements.sliceSize.dataflowNodes)}
+`;
+    }
+    return `${result}
+Shell close:                  ${print(stats.commonMeasurements, 'close R session')}
+Total:                        ${print(stats.commonMeasurements, 'total')}
+
+Input:
+  Number of lines:                     ${pad(stats.input.numberOfLines)}
+  Number of characters:                ${pad(stats.input.numberOfCharacters)}
+  Number of non whitespace characters: ${pad(stats.input.numberOfNonWhitespaceCharacters)}
+  Number of tokens:                    ${pad(stats.input.numberOfRTokens)}
+  Normalized R tokens:                 ${pad(stats.input.numberOfNormalizedTokens)}
+
+Dataflow:
+  Number of nodes:            ${pad(stats.dataflow.numberOfNodes)}
+  Number of edges:            ${pad(stats.dataflow.numberOfEdges)}
+  Number of calls:            ${pad(stats.dataflow.numberOfCalls)}
+  Number of function defs:    ${pad(stats.dataflow.numberOfFunctionDefinitions)}`;
+}
+exports.stats2string = stats2string;
+function ultimateStats2String(stats) {
+    // Used Slice Criteria Sizes:  ${formatSummarizedMeasure(stats.perSliceMeasurements.sliceCriteriaSizes)}
+    return `
+Summarized: ${stats.totalRequests} requests and ${stats.totalSlices} slices
+Shell init time:              ${formatSummarizedTimeMeasure(stats.commonMeasurements.get('initialize R session'))}
+Retrieval of token map:       ${formatSummarizedTimeMeasure(stats.commonMeasurements.get('retrieve token map'))}
+AST retrieval:                ${formatSummarizedTimeMeasure(stats.commonMeasurements.get('retrieve AST from R code'))}
+AST normalization:            ${formatSummarizedTimeMeasure(stats.commonMeasurements.get('normalize R AST'))}
+Dataflow creation:            ${formatSummarizedTimeMeasure(stats.commonMeasurements.get('produce dataflow information'))}
+
+Slice summary for:
+  Total:                      ${formatSummarizedTimeMeasure(stats.perSliceMeasurements.get('total'))}
+  Slice creation:             ${formatSummarizedTimeMeasure(stats.perSliceMeasurements.get('static slicing'))}
+  Reconstruction:             ${formatSummarizedTimeMeasure(stats.perSliceMeasurements.get('reconstruct code'))}
+  Failed to Re-Parse:         ${pad(stats.failedToRepParse)}/${stats.totalSlices}
+  Times hit Threshold:        ${pad(stats.timesHitThreshold)}/${stats.totalSlices} 
+  Reductions (reduced by x%):   
+    Number of lines:                     ${formatSummarizedMeasure(stats.reduction.numberOfLines, asPercentage)}
+    Number of lines no auto:             ${formatSummarizedMeasure(stats.reduction.numberOfLinesNoAutoSelection, asPercentage)}
+    Number of characters:                ${formatSummarizedMeasure(stats.reduction.numberOfCharacters, asPercentage)}
+    Number of non whitespace characters: ${formatSummarizedMeasure(stats.reduction.numberOfNonWhitespaceCharacters, asPercentage)}
+    Number of R tokens:                  ${formatSummarizedMeasure(stats.reduction.numberOfRTokens, asPercentage)}
+    Normalized R tokens:                 ${formatSummarizedMeasure(stats.reduction.numberOfNormalizedTokens, asPercentage)}
+    Number of dataflow nodes:            ${formatSummarizedMeasure(stats.reduction.numberOfDataflowNodes, asPercentage)}
+
+Shell close:                  ${formatSummarizedTimeMeasure(stats.commonMeasurements.get('close R session'))}
+Total:                        ${formatSummarizedTimeMeasure(stats.commonMeasurements.get('total'))}
+
+Input:
+  Number of lines:                     ${formatSummarizedMeasure(stats.input.numberOfLines)}
+  Number of characters:                ${formatSummarizedMeasure(stats.input.numberOfCharacters)}
+  Number of non whitespace characters: ${formatSummarizedMeasure(stats.input.numberOfNonWhitespaceCharacters)}
+  Number of tokens:                    ${formatSummarizedMeasure(stats.input.numberOfRTokens)}
+  Normalized R tokens:                 ${formatSummarizedMeasure(stats.input.numberOfNormalizedTokens)}
+
+Dataflow:
+  Number of nodes:            ${formatSummarizedMeasure(stats.dataflow.numberOfNodes)}
+  Number of edges:            ${formatSummarizedMeasure(stats.dataflow.numberOfEdges)}
+  Number of calls:            ${formatSummarizedMeasure(stats.dataflow.numberOfCalls)}
+  Number of function defs:    ${formatSummarizedMeasure(stats.dataflow.numberOfFunctionDefinitions)}`;
+}
+exports.ultimateStats2String = ultimateStats2String;
+//# sourceMappingURL=print.js.map

package/benchmark/stats/stats.d.ts

@@ -0,0 +1,41 @@
+import { SingleSlicingCriterion, SlicingCriteria } from '../../slicing';
+import { NodeId, RParseRequestFromFile, RParseRequestFromText } from '../../r-bridge';
+import { ReconstructionResult } from '../../slicing';
+export declare const CommonSlicerMeasurements: readonly ["initialize R session", "inject home path", "ensure installation of xmlparsedata", "retrieve token map", "retrieve AST from R code", "normalize R AST", "produce dataflow information", "close R session", "total"];
+export type CommonSlicerMeasurements = typeof CommonSlicerMeasurements[number];
+export declare const PerSliceMeasurements: readonly ["static slicing", "reconstruct code", "total"];
+export type PerSliceMeasurements = typeof PerSliceMeasurements[number];
+export type ElapsedTime = bigint;
+export interface PerSliceStats {
+    measurements: Map<PerSliceMeasurements, ElapsedTime>;
+    slicingCriteria: {
+        criterion: SingleSlicingCriterion;
+        id: NodeId;
+    }[];
+    reconstructedCode: ReconstructionResult;
+    numberOfDataflowNodesSliced: number;
+    timesHitThreshold: number;
+}
+export interface SlicerStatsInput<T = number> {
+    numberOfLines: T;
+    numberOfCharacters: T;
+    numberOfNonWhitespaceCharacters: T;
+    numberOfRTokens: T;
+    numberOfNormalizedTokens: T;
+}
+export interface SlicerStatsDataflow<T = number> {
+    numberOfNodes: T;
+    numberOfEdges: T;
+    numberOfCalls: T;
+    numberOfFunctionDefinitions: T;
+}
+/**
+ * The statistics that are collected by the {@link BenchmarkSlicer} and used for benchmarking.
+ */
+export interface SlicerStats {
+    commonMeasurements: Map<CommonSlicerMeasurements, ElapsedTime>;
+    perSliceMeasurements: Map<SlicingCriteria, PerSliceStats>;
+    request: RParseRequestFromFile | RParseRequestFromText;
+    input: SlicerStatsInput;
+    dataflow: SlicerStatsDataflow;
+}

package/benchmark/stats/stats.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerSliceMeasurements = exports.CommonSlicerMeasurements = void 0;
+exports.CommonSlicerMeasurements = ['initialize R session', 'inject home path', 'ensure installation of xmlparsedata', 'retrieve token map', 'retrieve AST from R code', 'normalize R AST', 'produce dataflow information', 'close R session', 'total'];
+exports.PerSliceMeasurements = ['static slicing', 'reconstruct code', 'total'];
+//# sourceMappingURL=stats.js.map

package/benchmark/stopwatch.d.ts

@@ -0,0 +1,35 @@
+export interface IStoppableStopwatch {
+    /** Stop the given stopwatch. */
+    stop(): void;
+}
+/**
+ * Allows to measure keys of type `T` with a `Stopwatch`.
+ *
+ * Measure with {@link start}, {@link measure} or {@link measureAsync}, retrieve the final measurements with {@link get}.
+ */
+export declare class Measurements<T> {
+    private measurements;
+    /**
+   * Start a timer for the given key, and guards that this is the first time this key is started.
+   * Call {@link IStoppableStopwatch#stop} on the returned stopwatch to stop the timer.
+   */
+    start(key: T): IStoppableStopwatch;
+    /**
+   * Automatically call {@link Measurements#start | start} and the corresponding stop to measure the execution time of the given function.
+   * @see {@link measureAsync}
+   */
+    measure<Out>(key: T, fn: () => Out): Out;
+    /**
+   * Similar to {@link measure}, but await the promise as part of the measurement
+   *
+     * @param key - The key to write the resulting measurement to
+     * @param fn  - The function to measure
+     *
+   * @see measure
+   */
+    measureAsync<Out>(key: T, fn: () => Promise<Out>): Promise<Out>;
+    /**
+   * Retrieve all measure-results, requires that all stop-watches that have been started have also been stopped.
+   */
+    get(): Map<T, bigint>;
+}

package/benchmark/stopwatch.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Measurements = void 0;
+const assert_1 = require("../util/assert");
+/** unguarded start-stop wrapper */
+class Stopwatch {
+    timeStart;
+    timeEnd;
+    stopped = false;
+    start() {
+        this.timeStart = process.hrtime.bigint();
+    }
+    stop() {
+        this.timeEnd = process.hrtime.bigint();
+        // check after to not affect measurements
+        (0, assert_1.guard)(!this.stopped, 'cannot stop a stopwatch twice');
+        this.stopped = true;
+    }
+    get() {
+        (0, assert_1.guard)(this.timeStart !== undefined && this.timeEnd !== undefined, 'cannot get elapsed time as the stopwatch has not been started/stopped');
+        return this.timeEnd - this.timeStart;
+    }
+}
+/**
+ * Allows to measure keys of type `T` with a `Stopwatch`.
+ *
+ * Measure with {@link start}, {@link measure} or {@link measureAsync}, retrieve the final measurements with {@link get}.
+ */
+class Measurements {
+    measurements = new Map();
+    /**
+   * Start a timer for the given key, and guards that this is the first time this key is started.
+   * Call {@link IStoppableStopwatch#stop} on the returned stopwatch to stop the timer.
+   */
+    start(key) {
+        // we guard *before* starting so there is no additional time penalty
+        (0, assert_1.guard)(!this.measurements.has(key), `already started stop watch for ${JSON.stringify(key)}`);
+        const stopwatch = new Stopwatch();
+        this.measurements.set(key, stopwatch);
+        stopwatch.start();
+        return stopwatch;
+    }
+    /**
+   * Automatically call {@link Measurements#start | start} and the corresponding stop to measure the execution time of the given function.
+   * @see {@link measureAsync}
+   */
+    measure(key, fn) {
+        const stopwatch = this.start(key);
+        const result = fn();
+        stopwatch.stop();
+        return result;
+    }
+    /**
+   * Similar to {@link measure}, but await the promise as part of the measurement
+   *
+     * @param key - The key to write the resulting measurement to
+     * @param fn  - The function to measure
+     *
+   * @see measure
+   */
+    async measureAsync(key, fn) {
+        const stopwatch = this.start(key);
+        const result = await fn();
+        stopwatch.stop();
+        return result;
+    }
+    /**
+   * Retrieve all measure-results, requires that all stop-watches that have been started have also been stopped.
+   */
+    get() {
+        const result = new Map();
+        for (const [key, stopwatch] of this.measurements) {
+            result.set(key, stopwatch.get());
+        }
+        return result;
+    }
+}
+exports.Measurements = Measurements;
+//# sourceMappingURL=stopwatch.js.map

package/cli/benchmark-app.d.ts

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

package/cli/benchmark-app.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const log_1 = require("../util/log");
+const files_1 = require("../util/files");
+const parallel_1 = require("../util/parallel");
+const assert_1 = require("../util/assert");
+const fs_1 = __importDefault(require("fs"));
+const common_1 = require("./common");
+const options = (0, common_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');
+function removeIfExists(summarizedRaw) {
+    if (fs_1.default.existsSync(summarizedRaw)) {
+        console.log(`Removing existing ${summarizedRaw}`);
+        fs_1.default.unlinkSync(summarizedRaw);
+    }
+}
+async function benchmark() {
+    removeIfExists(options.output);
+    console.log(`Writing output continuously to ${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 pool = new parallel_1.LimitedThreadPool(`${__dirname}/benchmark-helper-app`, files.map(f => [f.content, '--output', options.output, '--slice', options.slice, ...verboseAdd]), limit, options.parallel);
+    await pool.run();
+    const stats = pool.getStats();
+    console.log(`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,7 @@
+export interface SingleBenchmarkCliOptions {
+    verbose: boolean;
+    help: boolean;
+    input?: string;
+    slice: string;
+    output?: string;
+}

package/cli/benchmark-helper-app.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const log_1 = require("../util/log");
+const benchmark_1 = require("../benchmark");
+const slicing_1 = require("../slicing");
+const fs_1 = __importDefault(require("fs"));
+const json_1 = require("../util/json");
+const assert_1 = require("../util/assert");
+const common_1 = require("./common");
+const options = (0, common_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');
+    console.log(`[${options.input}] 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 benchmark_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(slicing_1.DefaultAllVariablesFilter, (i, total, arr) => console.log(`[${options.input}] Slicing ${i + 1}/${total} [${JSON.stringify(arr[i])}]`));
+            console.log(`[${options.input}] Completed Slicing`);
+            (0, assert_1.guard)(count > 0, `No possible slices found for ${options.input}, skipping in count`);
+        }
+        else {
+            console.log(`[${options.input}] Skipping Slicing due to --slice=${options.slice}`);
+        }
+        const { stats } = slicer.finish();
+        // append line by line
+        fs_1.default.appendFileSync(options.output, `${JSON.stringify({ filename: options.input, stats }, json_1.jsonReplacer)}\n`);
+    }
+    catch (e) {
+        if (e instanceof Error) {
+            if (!e.message.includes('unable to parse R')) {
+                console.log(`[${options.input}] 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 { FeatureKey } from '../../statistics';
+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 statistics_1 = require("../../statistics");
+const path_1 = __importDefault(require("path"));
+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 (!statistics_1.allFeatureNames.has(feature)) {
+            console.error(`Feature ${feature} is unknown, supported are ${[...statistics_1.allFeatureNames].join(', ')} or "all"`);
+            process.exit(1);
+        }
+    }
+    return features[0] === 'all' ? statistics_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/index.d.ts

@@ -0,0 +1,2 @@
+export * from './script';
+export * from './scripts-info';

package/cli/common/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("./script"), exports);
+__exportStar(require("./scripts-info"), exports);
+//# sourceMappingURL=index.js.map

package/cli/common/options.d.ts

@@ -0,0 +1,20 @@
+import { 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,82 @@
+"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 statistics_1 = require("../../statistics");
+/**
+ * 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: '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: `File to write all the measurements to in a per-file-basis (defaults to {italic benchmark-${StartTimeString}.json})`, defaultValue: `benchmark-${StartTimeString}.json`, 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: '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 = [...statistics_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 { 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;