@eagleoutice/flowr 2.6.1 → 2.6.3

package/documentation/data/server/doc-data-server-messages.js

@@ -16,8 +16,10 @@ const message_slice_1 = require("../../../cli/repl/server/messages/message-slice
 const message_repl_1 = require("../../../cli/repl/server/messages/message-repl");
 const message_query_1 = require("../../../cli/repl/server/messages/message-query");
 const example_query_code_1 = require("../query/example-query-code");
-const message_lineage_1 = require("../../../cli/repl/server/messages/message-lineage");
 const identify_link_to_last_call_relation_1 = require("../../../queries/catalog/call-context-query/identify-link-to-last-call-relation");
+/**
+ *
+ */
 function documentAllServerMessages() {
     (0, doc_server_message_1.documentServerMessage)({
         title: 'Hello',
@@ -67,7 +69,7 @@ Requests for the [REPL](#message-request-repl) are independent of that.
             return `
 	
 The request allows the server to analyze a file and prepare it for slicing.
-The message can contain a \`filetoken\`, which is used to identify the file in later slice or lineage requests (if you do not add one, the request will not be stored and therefore, it is not available for subsequent requests).
+The message can contain a \`filetoken\`, which is used to identify the file in later slice or query requests (if you do not add one, the request will not be stored and therefore, it is not available for subsequent requests).
 
 > **Please note!**\\
 > If you want to send and process a lot of analysis requests, but do not want to slice them, please do not pass the \`filetoken\` field. This will save the server a lot of memory allocation.
@@ -82,7 +84,7 @@ ${await (0, doc_server_message_1.documentServerMessageResponse)({
                 messages: [
                     {
                         type: 'request',
-                        description: `Let' suppose you simply want to analyze the following script:\n ${(0, doc_code_1.codeBlock)('r', 'x <- 1\nx + 1')}\n For this, you can send the following request:`,
+                        description: `Let's suppose you simply want to analyze the following script:\n ${(0, doc_code_1.codeBlock)('r', 'x <- 1\nx + 1')}\n For this, you can send the following request:`,
                         message: {
                             type: 'request-file-analysis',
                             id: '1',
@@ -478,66 +480,5 @@ See [above](#message-request-file-analysis) for the general structure of the res
 	`;
         }
     });
-    (0, doc_server_message_1.documentServerMessage)({
-        title: 'Lineage',
-        type: 'request',
-        definitionPath: '../cli/repl/server/messages/message-lineage.ts',
-        defRequest: message_lineage_1.requestLineageMessage,
-        defResponse: message_lineage_1.responseLineageMessage,
-        mermaidSequenceDiagram: `
-    Client->>+Server: request-lineage
-
-    alt
-        Server-->>Client: response-lineage
-    else
-        Server-->>Client: error
-    end
-    deactivate  Server
-	`,
-        shortDescription: `${deprecatedByQuery} Obtain the lineage of a given slicing criterion.`,
-        text: async (shell) => {
-            return `
-
-**We deprecated the lineage request in favor of the \`lineage\` [Query](${doc_files_1.FlowrWikiBaseRef}/Query%20API).**
-
-In order to retrieve the lineage of an object, you have to send a file analysis request first. The \`filetoken\` you assign is of use here as you can re-use it to repeatedly retrieve the lineage of the same file.
-Besides that, you will need to add a [criterion](${doc_files_1.FlowrWikiBaseRef}/Terminology#slicing-criterion) that specifies the object whose lineage you're interested in.
-
-${await (0, doc_server_message_1.documentServerMessageResponse)({
-                shell,
-                messageType: 'request-query',
-                messages: [{
-                        type: 'request',
-                        message: {
-                            type: 'request-file-analysis',
-                            id: '1',
-                            filetoken: 'x',
-                            content: 'x <- 1\nx + 1'
-                        }
-                    }, {
-                        type: 'response',
-                        expectedType: 'response-file-analysis',
-                        description: `
-See [above](#message-request-file-analysis) for the general structure of the response.
-			`
-                    }, {
-                        type: 'request',
-                        message: {
-                            type: 'request-lineage',
-                            id: '2',
-                            filetoken: 'x',
-                            criterion: '2@x'
-                        },
-                        mark: true
-                    }, {
-                        type: 'response',
-                        expectedType: 'response-lineage',
-                        description: 'The response contains the lineage of the desired object in form of an array of IDs (as the representation of a set).'
-                    }]
-            })}
-
-	`;
-        }
-    });
 }
 //# sourceMappingURL=doc-data-server-messages.js.map

package/documentation/doc-capabilities.d.ts

@@ -0,0 +1,9 @@
+import type { DocMakerArgs } from './wiki-mk/doc-maker';
+import { DocMaker } from './wiki-mk/doc-maker';
+/**
+ * https://github.com/flowr-analysis/flowr/wiki/Capabilities
+ */
+export declare class DocCapabilities extends DocMaker {
+    constructor();
+    protected text({ treeSitter }: DocMakerArgs): Promise<string>;
+}

package/documentation/{print-capabilities-markdown.js → doc-capabilities.js}

@@ -3,14 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocCapabilities = void 0;
 const data_1 = require("../r-bridge/data/data");
-const log_1 = require("../../test/functionality/_helper/log");
-const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
 const strings_1 = require("../util/text/strings");
 const doc_general_1 = require("./doc-util/doc-general");
-const tree_sitter_executor_1 = require("../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor");
 const fs_1 = __importDefault(require("fs"));
 const doc_structure_1 = require("./doc-util/doc-structure");
+const doc_maker_1 = require("./wiki-mk/doc-maker");
 const detailedInfoFile = 'coverage/flowr-test-details.json';
 function obtainDetailedInfos() {
     if (!fs_1.default.existsSync(detailedInfoFile)) {
@@ -130,8 +129,7 @@ async function printAsMarkdown(info, capabilities, depth = 0, lines = []) {
     return lines.join('\n');
 }
 function getPreamble() {
-    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'current capabilities' })}
-
+    return `
 Each capability has an id that can be used to link to it (use the link symbol to get a direct link to the capability).
 The internal id is also mentioned in the capability description. This id can be used to reference the capability in a labeled test within flowR.
 Besides, we use colored bullets like this:
@@ -154,21 +152,20 @@ Please prefer using a statement like "flowR has only partial support for feature
     })}
 `;
 }
-async function print(parser) {
-    /* check if the detailed test data is available */
-    if (!fs_1.default.existsSync(detailedInfoFile)) {
-        console.warn('\x1b[31mNo detailed test data available. Run the full tests (npm run test-full) to generate it.\x1b[m');
+/**
+ * https://github.com/flowr-analysis/flowr/wiki/Capabilities
+ */
+class DocCapabilities extends doc_maker_1.DocMaker {
+    constructor() {
+        super('wiki/Capabilities.md', module.filename, 'flowR capabilities overview');
+    }
+    async text({ treeSitter }) {
+        /* check if the detailed test data is available */
+        if (!fs_1.default.existsSync(detailedInfoFile)) {
+            console.warn('\x1b[31mNo detailed test data available. Run the full tests (npm run test-full) to generate it.\x1b[m');
+        }
+        return getPreamble() + await printAsMarkdown({ parser: treeSitter, info: obtainDetailedInfos() }, data_1.flowrCapabilities.capabilities);
     }
-    return getPreamble() + await printAsMarkdown({ parser, info: obtainDetailedInfos() }, data_1.flowrCapabilities.capabilities);
-}
-/** if we run this script, we want a Markdown representation of the capabilities */
-if (require.main === module) {
-    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
-    void tree_sitter_executor_1.TreeSitterExecutor.initTreeSitter().then(() => {
-        const parser = new tree_sitter_executor_1.TreeSitterExecutor();
-        void print(parser).then(str => {
-            console.log(str);
-        });
-    });
 }
-//# sourceMappingURL=print-capabilities-markdown.js.map
+exports.DocCapabilities = DocCapabilities;
+//# sourceMappingURL=doc-capabilities.js.map

package/documentation/doc-readme.d.ts

@@ -0,0 +1,9 @@
+import type { DocMakerArgs } from './wiki-mk/doc-maker';
+import { DocMaker } from './wiki-mk/doc-maker';
+/**
+ * https://github.com/flowr-analysis/flowr/blob/main/README.md
+ */
+export declare class DocReadme extends DocMaker {
+    constructor();
+    text({ treeSitter }: DocMakerArgs): Promise<string>;
+}

package/documentation/{print-readme.js → doc-readme.js}

@@ -1,8 +1,6 @@
 "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");
+exports.DocReadme = void 0;
 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");
@@ -15,9 +13,115 @@ 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");
 const doc_query_1 = require("./doc-util/doc-query");
-async function getText(shell) {
-    const dateOptions = { year: 'numeric', month: 'short', day: 'numeric' };
-    return `
+const doc_issue_1 = require("./doc-util/doc-issue");
+const strings_1 = require("../util/text/strings");
+const doc_maker_1 = require("./wiki-mk/doc-maker");
+const PublicationsMain = [
+    {
+        header: 'Statically Analyzing the Dataflow of R Programs (OOPSLA \'25)',
+        description: 'Please cite this paper if you are using flowR in your research.',
+        doi: 'https://doi.org/10.1145/3763087',
+        bibtex: `@article{10.1145/3763087,
+	author = {Sihler, Florian and Tichy, Matthias},
+	title = {Statically Analyzing the Dataflow of R Programs},
+	year = {2025},
+	issue_date = {October 2025},
+	publisher = {Association for Computing Machinery},
+	address = {New York, NY, USA},
+	volume = {9},
+	number = {OOPSLA2},
+	url = {https://doi.org/10.1145/3763087},
+	doi = {10.1145/3763087},
+	abstract = {The R programming language is primarily designed for statistical computing and mostly used by researchers without a background in computer science. R provides a wide range of dynamic features and peculiarities that are difficult to analyze statically like dynamic scoping and lazy evaluation with dynamic side effects. At the same time, the R ecosystem lacks sophisticated analysis tools that support researchers in understanding and improving their code.   In this paper, we present a novel static dataflow analysis framework for the R programming language that is capable of handling the dynamic nature of R programs and produces the dataflow graph of given R programs. This graph can be essential in a range of analyses, including program slicing, which we implement as a proof of concept. The core analysis works as a stateful fold over a normalized version of the abstract syntax tree of the R program, which tracks (re-)definitions, values, function calls, side effects, external files, and a dynamic control flow to produce one dataflow graph per program.   We evaluate the correctness of our analysis using output equivalence testing on a manually curated dataset of 779 sensible slicing points from executable real-world R scripts. Additionally, we use a set of systematic test cases based on the capabilities of the R language and the implementation of the R interpreter and measure the runtimes well as the memory consumption on a set of 4,230 real-world R scripts and 20,815 packages available on R’s package manager CRAN.   Furthermore, we evaluate the recall of our program slicer, its accuracy using shrinking, and its improvement over the state of the art. We correctly analyze almost all programs in our equivalence test suite, preserving the identical output for 99.7\\% of the manually curated slicing points. On average, we require 576ms to analyze the dataflow and around 213kB to store the graph of a research script.   This shows that our analysis is capable of analyzing real-world sources quickly and correctly. Our slicer achieves an average reduction of 84.8\\% of tokens indicating its potential to improve program comprehension.},
+	journal = {Proc. ACM Program. Lang.},
+	month = oct,
+	articleno = {309},
+	numpages = {29},
+	keywords = {Dataflow Analysis, R Programming Language, Static Analysis}
+}`
+    },
+    {
+        header: 'flowR: A Static Program Slicer for R (ASE \'24, Tool)',
+        description: `This refers to the tool-demonstration of the <a href="${doc_files_1.FlowrVsCode}">VS Code Extension</a>.`,
+        doi: 'https://doi.org/10.1145/3691620.3695359',
+        bibtex: `@inproceedings{DBLP:conf/kbse/SihlerT24,
+  author       = {Florian Sihler and
+                  Matthias Tichy},
+  editor       = {Vladimir Filkov and
+                  Baishakhi Ray and
+                  Minghui Zhou},
+  title        = {flowR: {A} Static Program Slicer for {R}},
+  booktitle    = {Proceedings of the 39th {IEEE/ACM} International Conference on Automated
+                  Software Engineering, {ASE} 2024, Sacramento, CA, USA, October 27
+                  - November 1, 2024},
+  pages        = {2390--2393},
+  publisher    = {{ACM}},
+  year         = {2024},
+  url          = {https://doi.org/10.1145/3691620.3695359},
+  doi          = {10.1145/3691620.3695359},
+  timestamp    = {Mon, 03 Mar 2025 21:16:51 +0100},
+  biburl       = {https://dblp.org/rec/conf/kbse/SihlerT24.bib},
+  bibsource    = {dblp computer science bibliography, https://dblp.org}
+}`
+    },
+    {
+        header: 'On the Anatomy of Real-World R Code for Static Analysis (MSR \'24)',
+        description: 'This paper lays the foundation for flowR by analyzing the characteristics of real-world R code.',
+        doi: 'https://doi.org/10.1145/3643991.3644911',
+        bibtex: `
+
+@inproceedings{DBLP:conf/msr/SihlerPSTDD24,
+  author       = {Florian Sihler and
+                  Lukas Pietzschmann and
+                  Raphael Straub and
+                  Matthias Tichy and
+                  Andor Diera and
+                  Abdelhalim Hafedh Dahou},
+  editor       = {Diomidis Spinellis and
+                  Alberto Bacchelli and
+                  Eleni Constantinou},
+  title        = {On the Anatomy of Real-World {R} Code for Static Analysis},
+  booktitle    = {21st {IEEE/ACM} International Conference on Mining Software Repositories,
+                  {MSR} 2024, Lisbon, Portugal, April 15-16, 2024},
+  pages        = {619--630},
+  publisher    = {{ACM}},
+  year         = {2024},
+  url          = {https://doi.org/10.1145/3643991.3644911},
+  doi          = {10.1145/3643991.3644911},
+  timestamp    = {Sun, 19 Jan 2025 13:31:27 +0100},
+  biburl       = {https://dblp.org/rec/conf/msr/SihlerPSTDD24.bib},
+  bibsource    = {dblp computer science bibliography, https://dblp.org}
+}`
+    }
+];
+const OtherWorksUsingFlowr = [
+    { name: 'Computational Reproducibility of R Code Supplements on OSF', doi: 'https://doi.org/10.36190/2025.49' },
+    { name: 'Multi-View Structural Graph Summaries', doi: 'https://doi.org/10.1109/WI-IAT62293.2024.00037' }
+];
+function printPublications() {
+    return PublicationsMain.map(pub => {
+        return `
+* [${pub.header}](${pub.doi})  
+  ${pub.description}
+  <details><summary>BibTeX</summary>
+  
+${(0, doc_general_1.prefixLines)((0, doc_code_1.codeBlock)('bibtex', pub.bibtex), '   ')}
+  
+  </details>
+		`.trim();
+    }).join('\n\n') + '\n\n Works using flowR include:\n' +
+        (0, strings_1.joinWithLast)(OtherWorksUsingFlowr.map(pub => `[${pub.name}](${pub.doi})`)) + '.\n';
+}
+/**
+ * https://github.com/flowr-analysis/flowr/blob/main/README.md
+ */
+class DocReadme extends doc_maker_1.DocMaker {
+    constructor() {
+        super('README.md', module.filename, 'flowR README', false);
+    }
+    async text({ treeSitter }) {
+        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)
@@ -38,18 +142,18 @@ It offers a wide variety of features, for example:
 	${(0, doc_general_1.prefixLines)((0, doc_structure_1.details)('Example: Linting code with flowR', `To lint your code, you can use the [REPL](${doc_files_1.FlowrWikiBaseRef}/Interface#using-the-repl) or the [Visual Studio Code extension](${doc_files_1.FlowrVsCode}) (see [vscode-flowr#283](https://github.com/flowr-analysis/vscode-flowr/pull/283)).
 	
 ${await (async () => {
-        const code = 'read.csv("/root/x.txt")';
-        const res = await (0, doc_query_1.showQuery)(shell, code, [{ type: 'linter' }], { showCode: false, collapseQuery: true, collapseResult: false });
-        return await (0, doc_repl_1.documentReplSession)(shell, [{
-                command: `:query @linter ${JSON.stringify(code)}`,
-                description: `
+            const code = 'read.csv("/root/x.txt")';
+            const res = await (0, doc_query_1.showQuery)(treeSitter, code, [{ type: 'linter' }], { showCode: false, collapseQuery: true, collapseResult: false });
+            return await (0, doc_repl_1.documentReplSession)(treeSitter, [{
+                    command: `:query @linter ${JSON.stringify(code)}`,
+                    description: `
 The linter will analyze the code and return any issues found.
 Formatted more nicely, this returns:
 
 ${res}
 		`
-            }]);
-    })()}
+                }]);
+        })()}
 	   
 	   `), '    ')}
 
@@ -71,10 +175,10 @@ ${(0, doc_code_1.codeBlock)('r', (0, doc_files_1.getFileContentFromRoot)('test/t
 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: ''
-        }])}
+${await (0, doc_repl_1.documentReplSession)(treeSitter, [{
+                command: ':query @static-slice (11@sum) file://test/testfiles/example.R',
+                description: ''
+            }])}
    
    `), '    ')}
 
@@ -105,12 +209,12 @@ ${(0, doc_code_1.codeBlock)('r', (0, doc_files_1.getFileContentFromRoot)('test/t
 
 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: `
+${await (0, doc_repl_1.documentReplSession)(treeSitter, [{
+                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 })}`
-        }])}
+${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, (0, doc_files_1.getFileContentFromRoot)('test/testfiles/example.R'), { showCode: false })}`
+            }])}
    
    `), '    ')}
 
@@ -155,6 +259,13 @@ If you want to use the same commands:
 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/).
 
+## 📃 Publications on flowR
+
+If you are interested in the theoretical background of _flowR_,
+please check out the following publications (if you find that a paper is missing here, please open [a new issue](${doc_issue_1.NewIssueUrl})):
+
+${printPublications()}
+
 ## 🚀 Contributing
 
 We welcome every contribution! Please check out the [developer onboarding](${doc_files_1.FlowrWikiBaseRef}/Onboarding) section in the wiki for all the information you will need.
@@ -180,17 +291,7 @@ If you want to make changes please edit the source file (the CI will take care o
 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
+exports.DocReadme = DocReadme;
+//# sourceMappingURL=doc-readme.js.map

package/documentation/doc-util/doc-auto-gen.d.ts

@@ -4,5 +4,11 @@ export interface AutoGenHeaderArguments {
     readonly filename: string;
     readonly purpose: string;
 }
+/**
+ *
+ */
 export declare function autoGenHeader({ rVersion, filename, purpose, currentDateAndTime }: AutoGenHeaderArguments): string;
+/**
+ *
+ */
 export declare function fileNameForGenHeader(filename: string): string;

package/documentation/doc-util/doc-auto-gen.js

@@ -4,9 +4,15 @@ exports.autoGenHeader = autoGenHeader;
 exports.fileNameForGenHeader = fileNameForGenHeader;
 const version_1 = require("../../util/version");
 const doc_files_1 = require("./doc-files");
+/**
+ *
+ */
 function autoGenHeader({ rVersion, filename, purpose, currentDateAndTime = new Date().toISOString().replace('T', ', ').replace(/\.\d+Z$/, ' UTC') }) {
     return `_This document was generated from '${fileNameForGenHeader(filename)}' on ${currentDateAndTime} presenting an overview of flowR's ${purpose} (v${(0, version_1.flowrVersion)().format()}${rVersion ? ', using R v' + rVersion : ''}). Please do not edit this file/wiki page directly._`;
 }
+/**
+ *
+ */
 function fileNameForGenHeader(filename) {
     const shortenFilename = filename.replace(/^.*src\//, 'src/');
     return (0, doc_files_1.linkFlowRSourceFile)(shortenFilename);

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

@@ -16,8 +16,22 @@ interface BenchmarkElementBench {
     readonly range: number;
     readonly extra: string;
 }
+/**
+ * Loads the benchmark data from the predefined path.
+ * This is the location which is used by the CI to store benchmark results.
+ */
 export declare function loadBenchmarkData(): Promise<BenchmarkData>;
+/**
+ * Returns the latest benchmark for the given suite.
+ */
 export declare function getLatestBenchmark(suite: string): Promise<BenchmarkElement>;
+/**
+ * Returns the timestamp of the last benchmark update.
+ * We can use this to find out when the last (recorded) benchmark run was.
+ */
 export declare function getLastBenchmarkUpdate(): Promise<number>;
+/**
+ * Get the total time taken for dataflow analysis in the given suite.
+ */
 export declare function getLatestDfAnalysisTime(suite: string): Promise<number>;
 export {};

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

@@ -44,6 +44,10 @@ 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;
+/**
+ * Loads the benchmark data from the predefined path.
+ * This is the location which is used by the CI to store benchmark results.
+ */
 async function loadBenchmarkData() {
     if (benchmarkData === null) {
         // provide a window object to attach to in the import
@@ -54,12 +58,19 @@ async function loadBenchmarkData() {
     }
     return benchmarkData;
 }
+/**
+ * Returns the latest benchmark for the given suite.
+ */
 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];
 }
+/**
+ * Returns the timestamp of the last benchmark update.
+ * We can use this to find out when the last (recorded) benchmark run was.
+ */
 async function getLastBenchmarkUpdate() {
     return (await loadBenchmarkData()).lastUpdate;
 }
@@ -68,6 +79,9 @@ function getBenchmarkElement(bench, name) {
     (0, assert_1.guard)(element, `No benchmark data for '${name}' found!`);
     return element;
 }
+/**
+ * Get the total time taken for dataflow analysis in the given suite.
+ */
 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));

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

@@ -2,7 +2,7 @@ import type { NormalizedAst } from '../../r-bridge/lang-4.x/ast/model/processing
 import type { KnownParser } from '../../r-bridge/parser';
 import type { DataflowInformation } from '../../dataflow/info';
 import type { ControlFlowInformation } from '../../control-flow/control-flow-graph';
-import type { CfgSimplificationPassName } from '../../control-flow/cfg-simplification';
+import { type CfgSimplificationPassName } from '../../control-flow/cfg-simplification';
 type GetCfgReturn = {
     info: ControlFlowInformation;
     ast: NormalizedAst;
@@ -10,6 +10,9 @@ type GetCfgReturn = {
 };
 export declare function getCfg(parser: KnownParser, code: string, simplifications?: readonly CfgSimplificationPassName[], useDfg?: true): Promise<Required<GetCfgReturn>>;
 export declare function getCfg(parser: KnownParser, code: string, simplifications?: readonly CfgSimplificationPassName[], useDfg?: boolean): Promise<GetCfgReturn>;
+/**
+ * Serializes the given control flow graph to a mermaid diagram.
+ */
 export declare function printCfg(cfg: ControlFlowInformation, ast: NormalizedAst, prefix?: string, simplify?: boolean): string;
 export interface PrintCfgOptions {
     readonly showCode?: boolean;
@@ -19,5 +22,8 @@ export interface PrintCfgOptions {
     readonly simplify?: boolean;
     readonly useDfg?: boolean;
 }
+/**
+ * Generates and prints the control flow graph for the given code, along with optional metadata and the original code.
+ */
 export declare function printCfgCode(parser: KnownParser, code: string, { showCode, openCode, prefix, simplifications, simplify, useDfg }?: PrintCfgOptions): Promise<string>;
 export {};

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

@@ -5,31 +5,37 @@ exports.printCfg = printCfg;
 exports.printCfgCode = printCfgCode;
 const extract_cfg_1 = require("../../control-flow/extract-cfg");
 const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
-const retriever_1 = require("../../r-bridge/retriever");
 const time_1 = require("../../util/text/time");
 const doc_files_1 = require("./doc-files");
 const cfg_1 = require("../../util/mermaid/cfg");
 const doc_code_1 = require("./doc-code");
 const cfg_simplification_1 = require("../../control-flow/cfg-simplification");
-const config_1 = require("../../config");
+const flowr_analyzer_context_1 = require("../../project/context/flowr-analyzer-context");
+/**
+ * Returns the control flow graph for the given code.
+ */
 async function getCfg(parser, code, simplifications = [], useDfg = true) {
-    const result = useDfg ? await (0, default_pipelines_1.createDataflowPipeline)(parser, {
-        request: (0, retriever_1.requestFromInput)(code)
-    }, config_1.defaultConfigOptions).allRemainingSteps() : await (0, default_pipelines_1.createNormalizePipeline)(parser, {
-        request: (0, retriever_1.requestFromInput)(code)
-    }, config_1.defaultConfigOptions).allRemainingSteps();
-    const cfg = (0, extract_cfg_1.extractCfg)(result.normalize, config_1.defaultConfigOptions, useDfg ? result.dataflow.graph : undefined, [...cfg_simplification_1.DefaultCfgSimplificationOrder, ...simplifications]);
+    const context = (0, flowr_analyzer_context_1.contextFromInput)(code);
+    const result = await (useDfg ? (0, default_pipelines_1.createDataflowPipeline)(parser, { context })
+        : (0, default_pipelines_1.createNormalizePipeline)(parser, { context })).allRemainingSteps();
+    const cfg = (0, extract_cfg_1.extractCfg)(result.normalize, context, useDfg ? result.dataflow.graph : undefined, [...cfg_simplification_1.DefaultCfgSimplificationOrder, ...simplifications]);
     return {
         info: cfg,
         ast: result.normalize,
         dataflow: 'dataflow' in result ? result.dataflow : undefined
     };
 }
+/**
+ * Serializes the given control flow graph to a mermaid diagram.
+ */
 function printCfg(cfg, ast, prefix = 'flowchart BT\n', simplify = false) {
     return `
 ${(0, doc_code_1.codeBlock)('mermaid', (0, cfg_1.cfgToMermaid)(cfg, ast, prefix, simplify))}
 	`;
 }
+/**
+ * Generates and prints the control flow graph for the given code, along with optional metadata and the original code.
+ */
 async function printCfgCode(parser, code, { showCode = true, openCode = false, prefix = 'flowchart BT\n', simplifications = [], simplify = false, useDfg = true } = {}) {
     const now = performance.now();
     const res = await getCfg(parser, code, simplifications, useDfg);

package/documentation/doc-util/doc-cli-option.d.ts

@@ -2,7 +2,16 @@
 import { scripts } from '../../cli/common/scripts-info';
 import { flowrMainOptionDefinitions } from '../../cli/flowr-main-options';
 type ScriptOptions<Type extends keyof typeof scripts | 'flowr'> = Type extends keyof typeof scripts ? typeof scripts[Type]['options'][number]['name'] : Type extends 'flowr' ? typeof flowrMainOptionDefinitions[number]['name'] : never;
+/**
+ *
+ */
 export declare function getCliLongOptionOf<ScriptName extends keyof typeof scripts | 'flowr', OptionName extends ScriptOptions<ScriptName>>(scriptName: ScriptName, optionName: OptionName, withAlias?: boolean, quote?: boolean): string;
+/**
+ *
+ */
 export declare function multipleCliOptions<ScriptName extends keyof typeof scripts | 'flowr', OptionName extends ScriptOptions<ScriptName>>(scriptName: ScriptName, ...options: OptionName[]): string;
+/**
+ *
+ */
 export declare function getReplCommand(commandName: string, quote?: boolean, showStar?: boolean): string;
 export {};

package/documentation/doc-util/doc-cli-option.js

@@ -10,6 +10,9 @@ const html_hover_over_1 = require("../../util/html-hover-over");
 const flowr_main_options_1 = require("../../cli/flowr-main-options");
 const repl_commands_1 = require("../../cli/repl/commands/repl-commands");
 const doc_escape_1 = require("./doc-escape");
+/**
+ *
+ */
 function getCliLongOptionOf(scriptName, optionName, withAlias = false, quote = true) {
     const script = scriptName === 'flowr' ? flowr_main_options_1.flowrMainOptionDefinitions : scripts_info_1.scripts[scriptName].options;
     (0, assert_1.guard)(script !== undefined, () => `Unknown script ${scriptName}, pick one of ${JSON.stringify(Object.keys(scripts_info_1.scripts))}.`);
@@ -22,9 +25,15 @@ function getCliLongOptionOf(scriptName, optionName, withAlias = false, quote = t
     // span ensures split even with ligatures
     return (0, html_hover_over_1.textWithTooltip)(`${char}-${ligatureBreaker}-${optionName}${char}`, 'Description (Command Line Argument): ' + description) + alias;
 }
+/**
+ *
+ */
 function multipleCliOptions(scriptName, ...options) {
     return options.map(o => getCliLongOptionOf(scriptName, o, false, true)).join(' ');
 }
+/**
+ *
+ */
 function getReplCommand(commandName, quote = true, showStar = false) {
     const availableNames = (0, repl_commands_1.getReplCommands)();
     const commands = availableNames[commandName];

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

@@ -1,3 +1,27 @@
+/**
+ * Produces a code block in markdown format.
+ * @example
+ * ```typescript
+ * codeBlock('ts', 'const x = 42;');
+ * // Produces:
+ * //
+ * // ```ts
+ * // const x = 42;
+ * // ```
+ * ```
+ */
 export declare function codeBlock(language: string, code: string): string;
+/**
+ * Produces an inline code span in markdown format.
+ * @example
+ * ```typescript
+ * codeInline('const x = 42;');
+ * // Produces: `<code>const x = 42;</code>`
+ * ```
+ */
 export declare function codeInline(code: string): string;
+/**
+ * Produces a JSON code block in markdown format, with optional length limit.
+ * If the pretty-printed JSON exceeds the limit, a message is shown instead of the full JSON.
+ */
 export declare function jsonWithLimit(object: object, maxLength?: number, tooLongText?: string): string;