@eagleoutice/flowr 2.2.3 → 2.2.5

package/documentation/doc-util/doc-benchmarks.js

@@ -0,0 +1,76 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadBenchmarkData = loadBenchmarkData;
+exports.getLatestBenchmark = getLatestBenchmark;
+exports.getLastBenchmarkUpdate = getLastBenchmarkUpdate;
+exports.getLatestDfAnalysisTime = getLatestDfAnalysisTime;
+const path_1 = __importDefault(require("path"));
+const assert_1 = require("../../util/assert");
+const BenchmarkDataPath = path_1.default.resolve(__dirname, '..', '..', '..', 'wiki', 'stats', 'benchmark', 'data.js');
+let benchmarkData = null;
+async function loadBenchmarkData() {
+    if (benchmarkData === null) {
+        // provide a window object to attach to in the import
+        globalThis['window'] = {};
+        await Promise.resolve(`${BenchmarkDataPath}`).then(s => __importStar(require(s)));
+        // @ts-expect-error -- we know that the data is there
+        benchmarkData = window['BENCHMARK_DATA'];
+    }
+    return benchmarkData;
+}
+async function getLatestBenchmark(suite) {
+    // provide a window object to attach to in the import
+    const suiteData = (await loadBenchmarkData()).entries[suite];
+    (0, assert_1.guard)(suiteData, `No benchmark data for suite '${suite}' found!`);
+    return suiteData.sort((a, b) => b.date - a.date)[0];
+}
+async function getLastBenchmarkUpdate() {
+    return (await loadBenchmarkData()).lastUpdate;
+}
+function getBenchmarkElement(bench, name) {
+    const element = bench.benches.find(b => b.name === name);
+    (0, assert_1.guard)(element, `No benchmark data for '${name}' found!`);
+    return element;
+}
+async function getLatestDfAnalysisTime(suite) {
+    const elem = await getLatestBenchmark(suite);
+    const [parse, normalize, analyze] = ['Retrieve AST from R code', 'Normalize R AST', 'Produce dataflow information'].map(name => getBenchmarkElement(elem, name));
+    return parse.value + normalize.value + analyze.value;
+}
+//# sourceMappingURL=doc-benchmarks.js.map

package/documentation/doc-util/doc-code.d.ts

@@ -1,2 +1,3 @@
 export declare function codeBlock(language: string, code: string | undefined): string;
+export declare function codeInline(code: string): string;
 export declare function jsonWithLimit(object: object, maxLength?: number, tooLongText?: string): string;

package/documentation/doc-util/doc-code.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.codeBlock = codeBlock;
+exports.codeInline = codeInline;
 exports.jsonWithLimit = jsonWithLimit;
 const json_1 = require("../../util/json");
 function codeBlock(language, code) {
     return `\n\`\`\`${language}\n${code?.trim() ?? ''}\n\`\`\`\n`;
 }
+function codeInline(code) {
+    return `<code>${code}</code>`;
+}
 function jsonWithLimit(object, maxLength = 5_000, tooLongText = '_As the code is pretty long, we inhibit pretty printing and syntax highlighting (JSON):_') {
     const prettyPrinted = JSON.stringify(object, json_1.jsonReplacer, 2);
     return `

package/documentation/doc-util/doc-files.d.ts

@@ -5,6 +5,7 @@ export declare const FlowrWikiBaseRef = "https://github.com/flowr-analysis/flowr
 export declare const FlowrNpmRef = "https://www.npmjs.com/package/@eagleoutice/flowr";
 export declare const FlowrDockerRef = "https://hub.docker.com/r/eagleoutice/flowr";
 export declare const FlowrCodecovRef = "https://app.codecov.io/gh/flowr-analysis/flowr";
+export declare const FlowrVsCode = "https://marketplace.visualstudio.com/items?itemName=code-inspect.vscode-flowr";
 export declare function getFilePathMd(path: string): string;
 export declare function getFileContentFromRoot(path: string): string;
 export declare function linkFlowRSourceFile(path: string): string;

package/documentation/doc-util/doc-files.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FlowrCodecovRef = exports.FlowrDockerRef = exports.FlowrNpmRef = exports.FlowrWikiBaseRef = exports.RemoteFlowrFilePathBaseRef = exports.FlowrSiteBaseRef = exports.FlowrGithubBaseRef = void 0;
+exports.FlowrVsCode = exports.FlowrCodecovRef = exports.FlowrDockerRef = exports.FlowrNpmRef = exports.FlowrWikiBaseRef = exports.RemoteFlowrFilePathBaseRef = exports.FlowrSiteBaseRef = exports.FlowrGithubBaseRef = void 0;
 exports.getFilePathMd = getFilePathMd;
 exports.getFileContentFromRoot = getFileContentFromRoot;
 exports.linkFlowRSourceFile = linkFlowRSourceFile;
@@ -15,6 +15,7 @@ exports.FlowrWikiBaseRef = `${exports.FlowrGithubBaseRef}/flowr/wiki`;
 exports.FlowrNpmRef = 'https://www.npmjs.com/package/@eagleoutice/flowr';
 exports.FlowrDockerRef = 'https://hub.docker.com/r/eagleoutice/flowr';
 exports.FlowrCodecovRef = 'https://app.codecov.io/gh/flowr-analysis/flowr';
+exports.FlowrVsCode = 'https://marketplace.visualstudio.com/items?itemName=code-inspect.vscode-flowr';
 function getFilePathMd(path) {
     // we go one up as we are in doc-util now :D #convenience
     const fullpath = require.resolve('../' + path);

package/documentation/doc-util/doc-server-message.js

@@ -80,7 +80,7 @@ async function documentServerMessageResponse({ shell, title, messageType, messag
                 try {
                     await socket.waitForMessage(metaMessage.expectedType, 20);
                 }
-                catch (e) {
+                catch {
                     console.error('Failed to receive message', metaMessage.expectedType, 'has', socket.getMessages());
                 }
             }

package/documentation/doc-util/doc-structure.d.ts

@@ -6,7 +6,7 @@ export interface DetailsOptions {
 }
 export declare function details(title: string, content: string, { color, open, hideIfEmpty, prefixInit }?: DetailsOptions): string;
 export interface BlockOptions {
-    readonly type: 'NOTE' | 'WARNING' | 'TIP';
+    readonly type: 'NOTE' | 'WARNING' | 'TIP' | 'IMPORTANT';
     readonly content: string;
 }
 export declare function block({ type, content }: BlockOptions): string;

package/documentation/doc-util/doc-structure.js

@@ -3,9 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.details = details;
 exports.block = block;
 const doc_general_1 = require("./doc-general");
-function details(title, content, { color = 'black', open = false, hideIfEmpty = true, prefixInit = '' } = {}) {
+function details(title, content, { color, open = false, hideIfEmpty = true, prefixInit = '' } = {}) {
     return hideIfEmpty && content.trim().length === 0 ? '' : `
-${prefixInit}<details${open ? ' open' : ''}><summary style="color:${color}">${title}</summary>
+${prefixInit}<details${open ? ' open' : ''}><summary style="${color ? 'color:' + color : ''}">${title}</summary>
 
 ${content}
 

package/documentation/doc-util/doc-types.d.ts

@@ -40,6 +40,7 @@ export declare function printHierarchy({ program, info, root, collapseFromNestin
 /**
  * Create a short link to a type in the documentation
  * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
+ *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
  * @param hierarchy - The hierarchy of types to search in
  * @param codeStyle - Whether to use code style for the link
  * @param realNameWrapper - How to highlight the function in name in the `x::y` format?

package/documentation/doc-util/doc-types.js

@@ -218,7 +218,7 @@ function collectHierarchyInformation(sourceFiles, options) {
     return hierarchyList;
 }
 function getTypePathLink({ filePath, lineNumber }, prefix = doc_files_1.RemoteFlowrFilePathBaseRef) {
-    const fromSource = filePath.replace(/^.*\/src\//, 'src/');
+    const fromSource = filePath.replace(/^.*\/src\//, 'src/').replace(/^.*\/test\//, 'test/');
     return `${prefix}/${fromSource}#L${lineNumber}`;
 }
 function generateMermaidClassDiagram(hierarchyList, rootName, options, visited = new Set()) {
@@ -348,20 +348,24 @@ function printHierarchy({ program, info, root, collapseFromNesting = 1, initialN
 function retrieveNode(name, hierarchy) {
     let container = undefined;
     if (name.includes('::')) {
-        [container, name] = name.split('::');
+        [container, name] = name.split(/:::?/);
     }
-    const node = hierarchy.find(e => e.name === name);
-    if (!node) {
+    let node = hierarchy.filter(e => e.name === name);
+    if (node.length === 0) {
         return undefined;
     }
-    else if (container && !node.extends.includes(container)) {
-        return undefined;
+    else if (container) {
+        node = node.filter(n => n.extends.includes(container));
+        if (node.length === 0) {
+            return undefined;
+        }
     }
-    return [container, name, node];
+    return [container, name, node[0]];
 }
 /**
  * Create a short link to a type in the documentation
  * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
+ *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
  * @param hierarchy - The hierarchy of types to search in
  * @param codeStyle - Whether to use code style for the link
  * @param realNameWrapper - How to highlight the function in name in the `x::y` format?
@@ -372,7 +376,11 @@ function shortLink(name, hierarchy, codeStyle = true, realNameWrapper = 'b') {
         console.error(`Could not find node ${name} when resolving short link!`);
         return '';
     }
-    const [pkg, mainName, node] = res;
+    const [, mainName, node] = res;
+    let pkg = res[0];
+    if (name.includes(':::')) {
+        pkg = undefined;
+    }
     const comments = node.comments?.join('\n').replace(/\\?\n|```[a-zA-Z]*|\s\s*/g, ' ').replace(/<\/?code>|`/g, '').replace(/<\/?p\/?>/g, ' ').replace(/"/g, '\'') ?? '';
     return `[${codeStyle ? '<code>' : ''}${(node.comments?.length ?? 0) > 0 ?
         (0, html_hover_over_1.textWithTooltip)(pkg ? `${pkg}::<${realNameWrapper}>${mainName}</${realNameWrapper}>` : mainName, comments.length > 400 ? comments.slice(0, 400) + '...' : comments) : node.name}${codeStyle ? '</code>' : ''}](${getTypePathLink(node)})`;

package/documentation/print-core-wiki.js

@@ -184,7 +184,14 @@ ${await (0, doc_repl_1.documentReplSession)(shell, [{
         }
     ], { openOutput: false })}
 	
-Especially when you are just starting with flowR, we recommend to use the REPL to explore the output of the different steps.
+${(0, doc_structure_1.block)({
+        type: 'TIP',
+        content: `
+	All of these commands accept file paths as well, so you can write longer R code within a file, and then pass 
+	the file path prefixed with \`${retriever_1.fileProtocol}\` (e.g., \`${retriever_1.fileProtocol}test/testfiles/example.R\`) to the commands.`
+    })}	
+
+Especially when you are just starting with flowR, we recommend using the REPL to explore the output of the different steps.
 
 ${(0, doc_structure_1.block)({
         type: 'NOTE',

package/documentation/print-interface-wiki.js

@@ -24,6 +24,7 @@ const pipeline_executor_1 = require("../core/pipeline-executor");
 const doc_structure_1 = require("./doc-util/doc-structure");
 const doc_types_1 = require("./doc-util/doc-types");
 const path_1 = __importDefault(require("path"));
+const tree_sitter_executor_1 = require("../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor");
 async function explainServer(shell) {
     (0, doc_data_server_messages_1.documentAllServerMessages)();
     return `
@@ -239,7 +240,7 @@ ${(0, schema_1.describeSchema)(config_1.flowrConfigFileSchema, ansi_1.markdownFo
 }
 function explainWritingCode(shell) {
     const types = (0, doc_types_1.getTypesFromFolderAsMermaid)({
-        rootFolder: path_1.default.resolve('./src/r-bridge/'),
+        rootFolder: path_1.default.resolve('./src/'),
         files: [path_1.default.resolve('./src/core/pipeline-executor.ts'), path_1.default.resolve('./src/core/steps/pipeline/default-pipelines.ts')],
         typeName: 'RShell',
         inlineTypes: doc_types_1.mermaidHide
@@ -251,20 +252,26 @@ _flowR_ can be used as a [module](${doc_files_1.FlowrNpmRef}) and offers several
 ### Using the ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} to Interact with R
 
 The ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} class allows interfacing with the \`R\` ecosystem installed on the host system.
-Please have a look at [flowR's engines](${doc_files_1.FlowrWikiBaseRef}/Engines) for more information on alterantives.
+Please have a look at [flowR's engines](${doc_files_1.FlowrWikiBaseRef}/Engines) for more information on alterantives (for example, the ${(0, doc_types_1.shortLink)(tree_sitter_executor_1.TreeSitterExecutor.name, types.info)}).
 
-> [!IMPORTANT]
-> Each ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} controls a new instance of the R&nbsp;interpreter, make sure to call <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.close.name}()</code> when you’re done.
+${(0, doc_structure_1.block)({
+        type: 'IMPORTANT',
+        content: `
+Each ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} controls a new instance of the R&nbsp;interpreter, 
+make sure to call ${(0, doc_code_1.codeInline)((0, doc_types_1.shortLink)(shell_1.RShell.name + '::' + shell.close.name, types.info, false, 'i') + '()')} when you are done.`
+    })}
 
-You can start a new "session" simply by constructing a new object with <code>new ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}()</code>.
+You can start a new "session" simply by constructing a new object with ${(0, doc_code_1.codeInline)('new ' + (0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false) + '()')}.
 
-However, there are several options that may be of interest (e.g., to automatically revive the shell in case of errors or to control the name location of the R process on the system).
+However, there are several options that may be of interest 
+(e.g., to automatically revive the shell in case of errors or to control the name location of the R process on the system).
 
-With a shell object (let's call it \`shell\`), you can execute R code by using <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.sendCommand.name}</code>, 
-for example \`shell.${shell.sendCommand.name}("1 + 1")\`. 
-However, this does not return anything, so if you want to collect the output of your command, use <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.sendCommandWithOutput.name}</code> instead.
+With a shell object (let's call it \`shell\`), you can execute R code by using ${(0, doc_types_1.shortLink)(shell_1.RShell.name + '::' + shell.sendCommand.name, types.info, true, 'i')}, 
+for example ${(0, doc_code_1.codeInline)('shell.' + (0, doc_types_1.shortLink)(shell_1.RShell.name + ':::' + shell.sendCommand.name, types.info, false) + '("1 + 1")')}. 
+However, this does not return anything, so if you want to collect the output of your command, use
+${(0, doc_types_1.shortLink)(shell_1.RShell.name + '::' + shell.sendCommandWithOutput.name, types.info, true, 'i')} instead.
 
-Besides that, the command <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.tryToInjectHomeLibPath.name}</code> may be of interest, as it enables all libraries available on the host system.
+Besides that, the command ${(0, doc_types_1.shortLink)(shell_1.RShell.name + '::' + shell.tryToInjectHomeLibPath.name, types.info)} may be of interest, as it enables all libraries available on the host system.
 
 ### The Pipeline Executor
 
@@ -284,22 +291,21 @@ const slice = await slicer.allRemainingSteps()
 // console.log(slice.reconstruct.code)
 `)}
 
-<details>
-
-<summary style='color:gray'>More Information</summary>
+${(0, doc_structure_1.details)('More Information', `
 
 If you compare this, with what you would have done with the old (and removed) \`SteppingSlicer\`, 
 this essentially just requires you to replace the \`SteppingSlicer\` with the ${(0, doc_types_1.shortLink)(pipeline_executor_1.PipelineExecutor.name, types.info)}
 and to pass the ${(0, doc_types_1.shortLink)('DEFAULT_SLICING_PIPELINE', types.info)} as the first argument.
 The ${(0, doc_types_1.shortLink)(pipeline_executor_1.PipelineExecutor.name, types.info)}...
 
-1. allows investigating the results of all intermediate steps
+1. Provides structures to investigate the results of all intermediate steps
 2. Can be executed step-by-step
 3. Can repeat steps (e.g., to calculate multiple slices on the same input)
 
 See the in-code documentation for more information.
 
-</details>
+	`)}
+
 
 ### Generate Statistics
 

package/documentation/print-linting-and-testing-wiki.js

@@ -9,6 +9,7 @@ const doc_files_1 = require("./doc-util/doc-files");
 const doc_structure_1 = require("./doc-util/doc-structure");
 const doc_types_1 = require("./doc-util/doc-types");
 const path_1 = __importDefault(require("path"));
+const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
 function getText() {
     const { info } = (0, doc_types_1.getTypesFromFolderAsMermaid)({
         rootFolder: path_1.default.resolve('./test'),
@@ -16,7 +17,8 @@ function getText() {
         typeName: 'parameter',
         inlineTypes: doc_types_1.mermaidHide
     });
-    return `
+    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'linting and testing definitions' })}
+
 For the latest code coverage information, see [codecov.io](${doc_files_1.FlowrCodecovRef}), 
 for the latest benchmark results, see the [benchmark results](${doc_files_1.FlowrSiteBaseRef}/wiki/stats/benchmark) wiki page.
 

package/documentation/print-readme.d.ts

@@ -0,0 +1 @@
+export {};

package/documentation/print-readme.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const shell_1 = require("../r-bridge/shell");
+const log_1 = require("../../test/functionality/_helper/log");
+const tree_sitter_executor_1 = require("../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor");
+const doc_files_1 = require("./doc-util/doc-files");
+const doc_code_1 = require("./doc-util/doc-code");
+const doc_cli_option_1 = require("./doc-util/doc-cli-option");
+const doc_benchmarks_1 = require("./doc-util/doc-benchmarks");
+const numbers_1 = require("../util/numbers");
+const html_hover_over_1 = require("../util/html-hover-over");
+const doc_structure_1 = require("./doc-util/doc-structure");
+const doc_repl_1 = require("./doc-util/doc-repl");
+const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
+const doc_general_1 = require("./doc-util/doc-general");
+const doc_dfg_1 = require("./doc-util/doc-dfg");
+async function getText(shell) {
+    const dateOptions = { year: 'numeric', month: 'short', day: 'numeric' };
+    return `
+[![flowR logo](https://raw.githubusercontent.com/wiki/flowr-analysis/flowr/img/flowR.png)](${doc_files_1.FlowrGithubBaseRef}/flowr/wiki)\\
+[![QA (and potentially deploy)](${doc_files_1.FlowrGithubBaseRef}/flowr/actions/workflows/qa.yaml/badge.svg)](${doc_files_1.FlowrGithubBaseRef}/flowr/actions/workflows/qa.yaml)
+[![codecov](https://codecov.io/gh/flowr-analysis/flowr/graph/badge.svg)](https://codecov.io/gh/flowr-analysis/flowr)
+[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/eagleoutice/flowr?logo=docker&logoColor=white&label=dockerhub)](${doc_files_1.FlowrDockerRef})
+[![latest tag](https://badgen.net/github/tag/flowr-analysis/flowr?label=latest&color=purple)](${doc_files_1.FlowrGithubBaseRef}/flowr/releases/latest)
+[![Marketplace](https://badgen.net/vs-marketplace/v/code-inspect.vscode-flowr)](${doc_files_1.FlowrVsCode})
+[![DOI](https://zenodo.org/badge/624819038.svg)](https://zenodo.org/doi/10.5281/zenodo.13319290)
+
+_flowR_ is a sophisticated, static [dataflow analyzer](https://en.wikipedia.org/wiki/Data-flow_analysis) for the [R programming language](https://www.r-project.org/).
+It offers a wide variety of features, for example:
+
+* 🍕 **program slicing**\\
+   Given a point of interest like the visualization of a plot, _flowR_ reduces the program to just the parts which are relevant
+   for the computation of the point of interest.
+
+${(0, doc_general_1.prefixLines)((0, doc_structure_1.details)('Example: Slicing with flowR', `
+The simplest way to retrieve slices is with flowR's [Visual Studio Code extension](${doc_files_1.FlowrVsCode}). 
+However, you can slice using the [REPL](${doc_files_1.FlowrWikiBaseRef}/Interface#using-the-repl) as well.
+This can help you if you want to reuse specific parts of an existing analysis within another context or if you want to understand
+what is happening in the code.
+
+For this, let's have a look at the example file, located at ${(0, doc_files_1.linkFlowRSourceFile)('test/testfiles/example.R')}:
+
+${(0, doc_code_1.codeBlock)('r', (0, doc_files_1.getFileContentFromRoot)('test/testfiles/example.R'))}
+
+Let's suppose we are interested only in the \`sum\` which is printed in line 11.
+To get a slice for this, you can use the following command:
+
+${await (0, doc_repl_1.documentReplSession)(shell, [{
+            command: ':slicer test/testfiles/example.R --criterion "11@sum"',
+            description: ''
+        }])}
+   
+   `), '    ')}
+
+* 📚 **dependency analysis**\\
+  Given your analysis project, flowR offers a plethora of so-called [queries](${doc_files_1.FlowrWikiBaseRef}/Query-API) to get more information about your code.
+  An important query is the [dependencies query](${doc_files_1.FlowrWikiBaseRef}/Query-API#dependencies-query), which shows you the library your project needs,
+  the data files it reads, the scripts it sources, and the data it outputs.
+  
+  ${(0, doc_general_1.prefixLines)((0, doc_structure_1.details)('Example: Dependency Analysis with flowR', `
+The following showcases the dependency view of the [Visual Studio Code extension](${doc_files_1.FlowrVsCode}):
+
+![Dependency Analysis](https://raw.githubusercontent.com/flowr-analysis/vscode-flowr/refs/heads/main/media/dependencies.png)
+  
+  `), '    ')}
+
+* 🚀 **fast data and control-flow graphs**\\
+  Within just ${'<i>' + (0, html_hover_over_1.textWithTooltip)((0, numbers_1.roundToDecimals)(await (0, doc_benchmarks_1.getLatestDfAnalysisTime)('"social-science" Benchmark Suite (tree-sitter)'), 1) + ' ms</i>', 'This measurement is automatically fetched from the latest benchmarks!')} (as of ${new Date(await (0, doc_benchmarks_1.getLastBenchmarkUpdate)()).toLocaleDateString('en-US', dateOptions)}), 
+  _flowR_ can analyze the data- and control-flow of the average real-world R script. See the [benchmarks](https://flowr-analysis.github.io/flowr/wiki/stats/benchmark) for more information,
+  and consult the [wiki pages](${doc_files_1.FlowrWikiBaseRef}/Dataflow-Graph) for more details on the dataflow graph.
+
+${(0, doc_general_1.prefixLines)((0, doc_structure_1.details)('Example: Generating a dataflow graph with flowR', `
+You can investigate flowR's analyses using the [REPL](${doc_files_1.FlowrWikiBaseRef}/Interface#using-the-repl).
+Commands like ${(0, doc_cli_option_1.getReplCommand)('dataflow*')} allow you to view a dataflow graph for a given R script.
+
+Let's have a look at the following example:
+
+${(0, doc_code_1.codeBlock)('r', (0, doc_files_1.getFileContentFromRoot)('test/testfiles/example.R'))}
+
+To get the dataflow graph for this script, you can use the following command:
+
+${await (0, doc_repl_1.documentReplSession)(shell, [{
+            command: ':dataflow* test/testfiles/example.R',
+            description: `
+Following the link output should show the following:
+${await (0, doc_dfg_1.printDfGraphForCode)(shell, (0, doc_files_1.getFileContentFromRoot)('test/testfiles/example.R'), { showCode: false })}`
+        }])}
+   
+   `), '    ')}
+
+If you want to use flowR and the features it provides, feel free to check out the:
+
+- [Visual Studio Code extension](${doc_files_1.FlowrVsCode}): provides access to flowR's capabilities directly in VS Code (also works in [vscode.dev](https://vscode.dev/))
+- [RStudio Addin](${doc_files_1.FlowrGithubBaseRef}/rstudio-addin-flowr): integrates flowR into [RStudio](https://posit.co/downloads/)
+- [R package](${doc_files_1.FlowrGithubBaseRef}/flowr-r-adapter): allows you to use flowR in your R scripts
+- [Docker image](${doc_files_1.FlowrDockerRef}): run flowR in a container, this also includes [flowR's server](${doc_files_1.FlowrWikiBaseRef}/Interface#communicating-with-the-server)
+- [NPM package](${doc_files_1.FlowrNpmRef}): include flowR in your TypeScript and JavaScript projects (e.g., used for the VS Code extension)
+ 
+## ⭐ Getting Started
+
+To get started with _flowR_ and its features, please check out the [Overview](${doc_files_1.FlowrGithubBaseRef}/flowr/wiki/Overview) wiki page. 
+The [Setup](${doc_files_1.FlowrGithubBaseRef}/flowr/wiki/Setup) wiki page explains how you can download and setup _flowR_ on your system. 
+With docker&nbsp;🐳️, the following line should be enough (and drop you directly into the read-eval-print loop):
+
+${(0, doc_code_1.codeBlock)('shell', 'docker run -it --rm eagleoutice/flowr')}
+
+You can enter ${(0, doc_cli_option_1.getReplCommand)('help')} to gain more information on its capabilities.
+
+<details>
+
+<summary>Example REPL session</summary>
+
+![Example of a simple REPL session](wiki/gif/repl-demo.gif)
+
+</details>
+
+## 📜 More Information
+
+For more details on how to use _flowR_ please refer to the [wiki pages](${doc_files_1.FlowrGithubBaseRef}/flowr/wiki),
+as well as the deployed [code documentation](https://flowr-analysis.github.io/flowr/doc/).
+
+## 🚀 Contributing
+
+We welcome every contribution! Please check out the [contributing guidelines](${doc_files_1.FlowrGithubBaseRef}/flowr/tree/main/.github/CONTRIBUTING.md) for more information.
+
+### Contributors
+
+<a href="https://github.com/flowr-analysis/flowr/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=flowr-analysis/flowr"  alt="flowR Contributors"/>
+</a>
+
+----
+
+*flowr* is actively developed by [Florian Sihler](https://eagleoutice.github.io/portfolio/) under the
+[GPLv3 License](LICENSE).\\
+It is partially supported by the German Research Foundation (DFG) under the grant [504226141](https://gepris.dfg.de/gepris/projekt/504226141) ("CodeInspector").
+
+----
+
+### Generation Notice
+
+Please notice that this file was generated automatically using the file ${(0, doc_auto_gen_1.fileNameForGenHeader)(module.filename)} as a source.\\
+If you want to make changes please edit the source file (the CI will take care of the rest).
+In fact, many files in the [wiki](${doc_files_1.FlowrWikiBaseRef}) are generated, so make sure to check for the source file if you want to make changes.
+
+`.trim();
+}
+/** if we run this script, we want a Markdown representation of the capabilities */
+if (require.main === module) {
+    void tree_sitter_executor_1.TreeSitterExecutor.initTreeSitter().then(() => {
+        (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
+        const shell = new shell_1.RShell();
+        void getText(shell).then(str => {
+            console.log(str);
+        }).finally(() => {
+            shell.close();
+        });
+    });
+}
+//# sourceMappingURL=print-readme.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -33,6 +33,7 @@
     "wiki:search-api": "ts-node src/documentation/print-search-wiki.ts",
     "wiki:linting-and-testing": "ts-node src/documentation/print-linting-and-testing-wiki.ts",
     "wiki:interface": "ts-node src/documentation/print-interface-wiki.ts",
+    "gen:readme": "ts-node src/documentation/print-readme.ts",
     "build": "tsc --project .",
     "build-dev": "npm run build && npm run build:copy-wasm",
     "build:bundle-flowr": "npm run build && esbuild --bundle dist/src/cli/flowr.js --platform=node --bundle --minify --external:clipboardy --target=node22 --outfile=dist/src/cli/flowr.min.js && npm run build:copy-wasm-min",
@@ -48,7 +49,7 @@
     "performance-test": "func() { cd test/performance/ && bash run-all-suites.sh $1 $2 $3 $4; cd ../../; }; func",
     "test-full": "npm run test:coverage -- --no-watch -- --make-summary --test-installation",
     "detect-circular-deps": "npx madge  --extensions ts,tsx --circular src/",
-    "checkup": "npm run flowr -- --execute \":version\" && npm run lint && npm run test-full -- --allowOnly=false && npm run test:system -- --no-watch && docker build -t test-flowr -f scripts/Dockerfile . && npm run doc && npm-run-all wiki:*"
+    "checkup": "npm run flowr -- --execute \":version\" && npm run lint && npm run test-full -- --allowOnly=false && npm run test:system -- --no-watch && docker build -t test-flowr -f scripts/Dockerfile . && npm run doc && npm run gen:readme && npm-run-all wiki:*"
   },
   "keywords": [
     "static code analysis",
@@ -60,21 +61,6 @@
   ],
   "author": "Florian Sihler",
   "license": "ISC",
-  "eslintConfig": {
-    "settings": {
-      "import/resolver": {
-        "node": {
-          "extensions": [
-            ".ts"
-          ]
-        }
-      }
-    },
-    "extends": [
-      "@eagleoutice/eslint-config-flowr"
-    ],
-    "rules": {}
-  },
   "typedocOptions": {
     "includeVersion": true,
     "plugin": [
@@ -183,48 +169,50 @@
     }
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.3.0",
-    "@commitlint/config-angular": "^19.3.0",
-    "@eagleoutice/eslint-config-flowr": "^1.0.14",
-    "@j-ulrich/release-it-regex-bumper": "^5.1.0",
+    "@commitlint/cli": "^19.7.1",
+    "@commitlint/config-angular": "^19.7.1",
+    "@eagleoutice/eslint-config-flowr": "^1.0.17",
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.20.0",
+    "@j-ulrich/release-it-regex-bumper": "^5.2.0",
     "@types/command-line-args": "^5.2.3",
     "@types/command-line-usage": "^5.0.4",
     "@types/n-readlines": "^1.0.6",
-    "@types/n3": "^1.16.4",
+    "@types/n3": "^1.21.1",
     "@types/object-hash": "^3.0.6",
-    "@types/semver": "^7.5.6",
+    "@types/semver": "^7.5.8",
     "@types/tmp": "^0.2.6",
-    "@types/ws": "^8.5.10",
-    "@typescript-eslint/eslint-plugin": "^7.8.0",
-    "@vitest/coverage-v8": "^2.1.4",
+    "@types/ws": "^8.5.14",
+    "@typescript-eslint/eslint-plugin": "^8.24.0",
+    "@vitest/coverage-v8": "^3.0.5",
     "esbuild": "^0.25.0",
-    "eslint": "^8.57.1",
+    "eslint": "^9.20.1",
     "license-checker": "^25.0.1",
     "npm-run-all": "^4.1.5",
-    "release-it": "^17.6.0",
+    "release-it": "^18.1.2",
     "ts-node": "^10.9.2",
-    "typedoc": "^0.26.7",
-    "typedoc-plugin-missing-exports": "^3.0.0",
-    "typedoc-theme-hierarchy": "^5.0.3",
-    "typedoc-umlclass": "^0.10.0",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.4"
+    "typedoc": "^0.27.7",
+    "typedoc-plugin-missing-exports": "^3.1.0",
+    "typedoc-theme-hierarchy": "^5.0.4",
+    "typedoc-umlclass": "^0.10.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
   },
   "dependencies": {
-    "@xmldom/xmldom": "^0.9.2",
+    "@xmldom/xmldom": "^0.9.7",
     "clipboardy": "^4.0.0",
-    "command-line-args": "^6.0.0",
+    "command-line-args": "^6.0.1",
     "command-line-usage": "^7.0.3",
     "joi": "^17.13.3",
     "n-readlines": "^1.0.1",
-    "n3": "^1.21.3",
+    "n3": "^1.23.1",
     "object-hash": "^3.0.0",
     "object-sizeof": "^2.6.5",
-    "rotating-file-stream": "^3.2.5",
-    "semver": "^7.6.3",
+    "rotating-file-stream": "^3.2.6",
+    "semver": "^7.7.1",
     "tar": "^7.4.3",
     "tmp": "^0.2.3",
-    "ts-essentials": "^10.0.2",
+    "ts-essentials": "^10.0.4",
     "tslog": "^4.9.3",
     "web-tree-sitter": "^0.24.7",
     "ws": "^8.18.0",