@eagleoutice/flowr 2.6.0 → 2.6.2

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

@@ -30,6 +30,9 @@ const doc_code_1 = require("./doc-code");
 const doc_structure_1 = require("./doc-structure");
 const html_hover_over_1 = require("../../util/html-hover-over");
 const doc_general_1 = require("./doc-general");
+/**
+ *
+ */
 function getTypeScriptSourceFiles(fileNames) {
     try {
         const program = typescript_1.default.createProgram(fileNames, {
@@ -50,6 +53,9 @@ function getTypeScriptSourceFiles(fileNames) {
         return { files: [], program: undefined };
     }
 }
+/**
+ *
+ */
 function dropGenericsFromTypeName(type) {
     let previous;
     do {
@@ -58,6 +64,9 @@ function dropGenericsFromTypeName(type) {
     } while (type !== previous);
     return type;
 }
+/**
+ *
+ */
 function removeCommentSymbolsFromTypeScriptComment(comment) {
     return comment
         // remove '/** \n * \n */...
@@ -66,6 +75,9 @@ function removeCommentSymbolsFromTypeScriptComment(comment) {
         .replace(/\{@[a-zA-Z]+ ([^}]+\|)?(?<name>[^}]+)}/gm, '<code>$<name></code>')
         .trim();
 }
+/**
+ *
+ */
 function getTextualCommentsFromTypeScript(node) {
     const comments = typescript_1.default.getJSDocCommentsAndTags(node);
     const out = [];
@@ -81,15 +93,24 @@ function getTextualCommentsFromTypeScript(node) {
     }
     return out;
 }
+/**
+ *
+ */
 function getStartLineOfTypeScriptNode(node, sourceFile) {
     const lineStart = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line;
     return lineStart + 1;
 }
+/**
+ *
+ */
 function getType(node, typeChecker) {
     const tryDirect = typeChecker.getTypeAtLocation(node);
     return tryDirect ? typeChecker.typeToString(tryDirect) : 'unknown';
 }
 const defaultSkip = ['Pick', 'Partial', 'Required', 'Readonly', 'Omit', 'DeepPartial', 'DeepReadonly', 'DeepWritable', 'StrictOmit'];
+/**
+ *
+ */
 function followTypeReference(type, sourceFile) {
     const node = type.typeName;
     if (typescript_1.default.isQualifiedName(node)) {
@@ -250,9 +271,15 @@ function collectHierarchyInformation(sourceFiles, options) {
     });
     return hierarchyList;
 }
+/**
+ *
+ */
 function getTypePathForTypeScript({ filePath }) {
     return filePath.replace(/^.*\/src\//, 'src/').replace(/^.*\/test\//, 'test/');
 }
+/**
+ *
+ */
 function getTypePathLink(elem, prefix = doc_files_1.RemoteFlowrFilePathBaseRef) {
     const fromSource = getTypePathForTypeScript(elem);
     return `${prefix}/${fromSource}#L${elem.lineNumber}`;
@@ -347,6 +374,9 @@ function getTypesFromFolder(options) {
     }
     return getTypesFromFileAsMermaid(files, options);
 }
+/**
+ *
+ */
 function implSnippet(node, program, showName = true, nesting = 0, open = false) {
     (0, assert_1.guard)(node !== undefined, 'Node must be defined => invalid change of type name?');
     const indent = ' '.repeat(nesting * 2);
@@ -362,6 +392,9 @@ function implSnippet(node, program, showName = true, nesting = 0, open = false)
     return ` ${indent}${showName ? init : ''} ${text.replaceAll('\t', '    ').split(/\n/g).join(`\n${indent}   `)}`;
 }
 exports.mermaidHide = ['Leaf', 'Location', 'Namespace', 'Base', 'WithChildren', 'Partial', 'RAccessBase'];
+/**
+ *
+ */
 function printHierarchy({ program, info, root, collapseFromNesting = 1, initialNesting = 0, maxDepth = 20, openTop }) {
     if (initialNesting > maxDepth) {
         return '';
@@ -387,6 +420,9 @@ function printHierarchy({ program, info, root, collapseFromNesting = 1, initialN
         return thisLine + (out ? '\n' + out : '');
     }
 }
+/**
+ *
+ */
 function printCodeOfElement({ program, info, dropLinesEnd = 0, dropLinesStart = 0, doNotAutoGobble, hideDefinedAt }, name) {
     const node = info.find(e => e.name === name);
     if (!node) {
@@ -473,6 +509,9 @@ function shortLink(name, hierarchy, codeStyle = true, realNameWrapper = 'b') {
     return `<a href="${getTypePathLink(node)}">${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>' : ''}</a>`;
 }
+/**
+ *
+ */
 function shortLinkFile(name, hierarchy) {
     const res = retrieveNode(name, hierarchy);
     if (!res) {
@@ -482,6 +521,9 @@ function shortLinkFile(name, hierarchy) {
     const [, , node] = res;
     return `<a href="${getTypePathLink(node)}">${getTypePathForTypeScript(node)}</a>`;
 }
+/**
+ *
+ */
 function getDocumentationForType(name, hierarchy, prefix = '', filter) {
     const res = retrieveNode(name, hierarchy, filter?.fuzzy, filter?.type);
     if (!res) {

package/documentation/print-analyzer-wiki.js

@@ -74,6 +74,10 @@ ${(0, doc_types_1.printCodeOfElement)({ program: types.program, info: types.info
 		`
     })} 
 
+In general, we work on providing a set of example repositories that demonstrate how to use the analyzer in different scenarios:
+
+* [${doc_files_1.FlowrGithubGroupName}/sample-analyzer-project-query](${doc_files_1.FlowrGithubBaseRef}/sample-analyzer-project-query) for an example project that runs queries on an R project
+
 **TODO**: mention [Context](#Context_Information) 
 
 ${(0, doc_structure_1.section)('Builder Configuration', 2)}

package/documentation/print-core-wiki.d.ts

@@ -1,2 +1,5 @@
 import { FlowrAnalyzer } from '../project/flowr-analyzer';
+/**
+ *
+ */
 export declare function inspectContextExample(analyzer: FlowrAnalyzer): void;

package/documentation/print-core-wiki.js

@@ -69,6 +69,9 @@ async function sliceQueryExample(analyzer) {
         }]);
     return result;
 }
+/**
+ *
+ */
 function inspectContextExample(analyzer) {
     const ctx = analyzer.inspectContext();
     console.log('dplyr version', ctx.deps.getDependency('dplyr'));
@@ -247,7 +250,7 @@ ${(0, doc_structure_1.block)({
         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.
 
@@ -353,7 +356,7 @@ All ids conform to the ${(0, doc_types_1.shortLink)('NodeId', info)} type.
 
 The core of the dataflow graph generation works as a "stateful [fold](https://en.wikipedia.org/wiki/Fold_(higher-order_function))", 
 which uses the tree-like structure of the AST to combine the dataflow information of the children, while tracking the currently active variables and control flow 
-information as a “backpack” (state).	
+information as a “backpack” (state).
 We use the ${(0, doc_types_1.shortLink)(extractor_1.produceDataFlowGraph.name, info)} function as an entry point to the dataflow generation (the actual fold entry is in ${(0, doc_types_1.shortLink)(processor_1.processDataflowFor.name, info)}).
 The function is mainly backed by its ${(0, doc_types_1.shortLink)('processors', info)} object which maps each type in the normalized AST to an appropriate handler ("fold-function").
 

package/documentation/print-dataflow-graph-wiki.js

@@ -196,8 +196,6 @@ These origins may hold the name of any processor that is part of the ${(0, doc_t
 The entry \`function\` signals that flowR used a processor for a user-defined function defined within the source code, \`unnamed\` signals that the function as an anonymous function definition.
 However, in general, flowR may use any fitting handler as an origin. For example, within a access definition, flowR will correspondingly redefine the meaning of \`:=\` to that of the \`table:assign\`. 
 
-
-
 ${(0, doc_structure_1.details)('Example: Simple Function Call (unresolved)', await (async () => {
                 const code = 'foo(x,3,y=3,)';
                 const [text, info] = await (0, doc_dfg_1.printDfGraphForCode)(shell, code, { mark: new Set([8]), exposeResult: true });
@@ -323,7 +321,7 @@ ${await (async () => {
                     const name = interestingVertex.name;
                     (0, assert_1.guard)(name !== undefined, () => 'Could not find name for interesting assignment vertex');
                     return `
-${text}		
+${text}
 
 Interesting program, right? Running this with \`u <- TRUE\` will cause the last line to evaluate to \`6\` because we redefined the assignment
 operator to mean multiplication, while with \`u <- FALSE\` causes \`x\` to be assigned to \`3\`.
@@ -714,8 +712,8 @@ Yet, you may choose to follow these references for other queries. For now, _flow
 Besides the obvious quotation there are other cases in which _flowR_ may choose to create a ${linkEdgeName(edge_1.EdgeType.NonStandardEvaluation)} edge, there are
 some that may appear to be counter-intuitive. For example, a for-loop body, as in the following example.
 
-${(0, doc_structure_1.details)('Example: For-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'for(i in v) b', { mark: new Set([2, '4->2']) }))}	
-${(0, doc_structure_1.details)('Example: While-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'while(TRUE) b', { mark: new Set([1, '3->1']) }))}	
+${(0, doc_structure_1.details)('Example: For-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'for(i in v) b', { mark: new Set([2, '4->2']) }))}
+${(0, doc_structure_1.details)('Example: While-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'while(TRUE) b', { mark: new Set([1, '3->1']) }))}
 
 				`
             })}
@@ -789,6 +787,8 @@ wiki page if you are unsure.
 > When using _flowR_ as a library, you may use the functions in ${(0, doc_files_1.getFilePathMd)('../util/mermaid/dfg.ts')}.
 > 
 > If you receive a dataflow graph in its serialized form (e.g., by talking to a [_flowR_ server](${doc_files_1.FlowrWikiBaseRef}/Interface)), you can use ${(0, doc_types_1.shortLink)(`${graph_1.DataflowGraph.name}::${graph_1.DataflowGraph.fromJson.name}`, vertexType.info, true, 'i')} to retrieve the graph from the JSON representation.
+>
+> Also, check out the [${doc_files_1.FlowrGithubGroupName}/sample-analyzer-df-diff](${doc_files_1.FlowrGithubBaseRef}/sample-analyzer-df-diff) repository for a complete example project creating and comparing dataflow graphs.
 
 ${await (0, doc_dfg_1.printDfGraphForCode)(shell, 'x <- 3\ny <- x + 1\ny')}
 
@@ -921,8 +921,8 @@ ${(0, doc_types_1.printHierarchy)({ program: vertexType.program, info: vertexTyp
 Let's start by looking at the properties of the dataflow information object: ${Object.keys(result).map(k => `\`${k}\``).join(', ')}.
 
 ${(() => {
-            /* this includes the meta field for timing */
-            (0, assert_1.guard)(Object.keys(result).length === 8, () => 'Update Dataflow Documentation!');
+            /* this includes the meta field for timing and the quick CFG in order to enable re-use and improve performance */
+            (0, assert_1.guard)(Object.keys(result).length === 9, () => 'Update Dataflow Documentation!');
             return '';
         })()}
 

package/documentation/print-faq-wiki.js

@@ -2,87 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const log_1 = require("../../test/functionality/_helper/log");
 const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
-const doc_files_1 = require("./doc-util/doc-files");
-const doc_code_1 = require("./doc-util/doc-code");
+const faqs_1 = require("./data/faq/faqs");
 function print() {
+    const faqs = (0, faqs_1.registerFaqs)();
     return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'frequently asked questions' })}
 	
-## 💮 *flowR* FAQ
-
-### 🧑‍💻 *flowR* Development
-
-${qAndA('What are test labels and how do they work?', `
-Tests are labeled based on the *flowR* capabilities that they test for. The list of supported capabilities can be found on the [Capabilities](${doc_files_1.FlowrWikiBaseRef}/Capabilities) wiki page. For more extensive information on test labels, see the [test labels wiki section](${doc_files_1.FlowrWikiBaseRef}/Linting-and-Testing#test-labels).
-`)}
-
-${qAndA('How to get a REPL with debug-info/hot-reload?', `
-To enter the development repl, execute \`npm run main-dev\` in contrast to \`npm run flowr\` this will use an unminified build (keeping debug info)
-and will also watch the source files for changes and automatically recompile them. Please note, that this may have negative performance implications.
-`)}
-
-${qAndA('How do I generate mermaid diagrams?', `
-There are several ways to generate mermaid diagrams based on the input data that you want to use.
-- From the AST (abstract syntax tree): ${(0, doc_files_1.getFilePathMd)('../util/mermaid/ast.ts')}
-- From the CFG (control flow graph): ${(0, doc_files_1.getFilePathMd)('../util/mermaid/cfg.ts')}
-- From the DFG (dataflow graph): ${(0, doc_files_1.getFilePathMd)('../util/mermaid/dfg.ts')}
-`)}
-
-${qAndA('How do I create new wiki pages?', `
-To create an automatically generated wiki page, you can follow these steps:
-- Create a new file in \`src/documentation\` with a name like \`print-my-page-wiki.ts\`.
-- Add a new wiki generation script to the ${(0, doc_files_1.getFilePathMd)('../../package.json')}. You can copy one of the existing ones of the form \`"wiki:my-page": "ts-node src/documentation/print-my-page-wiki.ts"\`.
-- Add the wiki generation script to the \`broken-links-and-wiki.yml\` GitHub workflow file to enable automatic generation through the CI. You can copy one of the existing ones of the form \`update_page wiki/"My page" wiki:my-page\`.
-
-You can test your page by piping the wiki generation script to a file. For example, you can run the following command:
-${(0, doc_code_1.codeBlock)('shell', 'npm run --silent wiki:my-page > __my-page.md')}
-
-Remember not to commit this file, as it's only meant for testing.
-`)}
-
-${qAndA('Why can\'t I pass arguments when running flowR with npm?', `
-With \`npm\` you have to pass arguments in a specific way. The \`--\` operator is used to separate the \`npm\` arguments from the script arguments. For example, if you want to run \`flowR\` with the \`--help\` argument, you can use the following command:
-${(0, doc_code_1.codeBlock)('shell', 'npm run flowR -- --help')}
-`)}
-
-${qAndA('How to do logging in flowR?', `
-Check out the [Logging Section in the Linting and Testing wiki page](${doc_files_1.FlowrWikiBaseRef}/Linting-and-Testing#logging) for more information on how to do logging in *flowR*.
-`)}
-
-## 🇷 R FAQ
-
-### 📦 R Packages
-
-${qAndA('What is the R prelude and R base package?', `
-The base package contains lots of base functions like \`source\` for example. 
-The R prelude includes the base package along with several other packages.
-Packages that were loaded by the prelude can be called without prefixing the function call with the package name and the \`::\` operator. 
-
-The packages loaded by the R prelude can be seen in the \`attached base packages\` sections in the output of \`sessionInfo()\`.
-`)}
-
-${qAndA('How to get documentation for a function or package?', `
-There are a couple of ways to get documentation for a function or package. 
-
-🖥️ Firstly, if you have already installed the package the function originated from you can simply run \`?<package name>::<function name>\` in an R session to print the 
-relevant documentation. If you don't know the origin of the package, you can use 
-\`??<function name>\` in an R shell to fuzzy find all documentations containing 
-\`<function name>\` or something similar. 
-
-🌐 Secondly, if you don't have or don't want to install the package you can simply google the fully qualified name of the function. Good sources include \`rdrr.io\`
-or \`rdocumentation.org\`. Additionally, the package documentation PDF can also
-be downloaded directly from \`cran\`.  
-`)}
+	${faqs.toMarkdown()}
 
     `.trim();
 }
-function qAndA(question, answer) {
-    return `<details>
-<summary><strong>${question}</strong></summary>
-
-${answer.trim()}
-
-</details>`;
-}
 if (require.main === module) {
     (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
     console.log(print());

package/documentation/print-interface-wiki.js

@@ -154,7 +154,7 @@ ${await (0, doc_repl_1.documentReplSession)(shell, [{
 
 <details>
 
-<summary>File Content</summary>	
+<summary>File Content</summary>
 
 ${(0, doc_code_1.codeBlock)('r', (0, doc_files_1.getFileContentFromRoot)('test/testfiles/example.R'))}
 

package/documentation/print-onboarding-wiki.js

@@ -5,7 +5,7 @@ const doc_files_1 = require("./doc-util/doc-files");
 const doc_code_1 = require("./doc-util/doc-code");
 const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
 function print() {
-    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'developer onboarding process' })}	
+    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'developer onboarding process' })}
 	
 To get started developing on *flowR*, we recommend carefully reading the following pages:
 - 💻 [Setting up the *flowR* development environment](${doc_files_1.FlowrWikiBaseRef}/Setup#%EF%B8%8F-building-from-scratch).\

package/documentation/print-query-wiki.js

@@ -22,7 +22,6 @@ const id_map_query_executor_1 = require("../queries/catalog/id-map-query/id-map-
 const normalized_ast_query_executor_1 = require("../queries/catalog/normalized-ast-query/normalized-ast-query-executor");
 const cluster_query_executor_1 = require("../queries/catalog/cluster-query/cluster-query-executor");
 const static_slice_query_executor_1 = require("../queries/catalog/static-slice-query/static-slice-query-executor");
-const lineage_query_executor_1 = require("../queries/catalog/lineage-query/lineage-query-executor");
 const dependencies_query_executor_1 = require("../queries/catalog/dependencies-query/dependencies-query-executor");
 const doc_cli_option_1 = require("./doc-util/doc-cli-option");
 const doc_issue_1 = require("./doc-util/doc-issue");
@@ -39,6 +38,7 @@ const doc_cfg_1 = require("./doc-util/doc-cfg");
 const df_shape_query_executor_1 = require("../queries/catalog/df-shape-query/df-shape-query-executor");
 const _00_slice_1 = require("../core/steps/all/static-slicing/00-slice");
 const doc_repl_1 = require("./doc-util/doc-repl");
+const inspect_higher_order_query_executor_1 = require("../queries/catalog/inspect-higher-order-query/inspect-higher-order-query-executor");
 (0, doc_query_1.registerQueryDocumentation)('call-context', {
     name: 'Call-Context Query',
     type: 'active',
@@ -165,37 +165,6 @@ ${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
 		`;
     }
 });
-(0, doc_query_1.registerQueryDocumentation)('lineage', {
-    name: 'Lineage Query',
-    type: 'active',
-    shortDescription: 'Returns lineage of a criteria.',
-    functionName: lineage_query_executor_1.executeLineageQuery.name,
-    functionFile: '../queries/catalog/lineage-query/lineage-query-executor.ts',
-    buildExplanation: async (shell) => {
-        const exampleCode = 'x <- 1\nx';
-        return `
-This query calculates the _lineage_ of a given slicing criterion. The lineage traces back all parts that the
-respective variables stems from given the reads, definitions, and returns in the dataflow graph.
-
-To understand this, let's start with a simple example query, to get the lineage of the second use of \`x\` in the following code:
-${(0, doc_code_1.codeBlock)('r', exampleCode)}
- 
-For this, we use the criterion \`2@x\` (which is the first use of \`x\` in the second line).
- 
-${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
-                type: 'lineage',
-                criterion: '2@x'
-            }], { showCode: false })}
-
-In this simple scenario, the _lineage_ is equivalent to the slice (and in-fact the complete code). 
-In general the lineage is smaller and makes no guarantees on executability. 
-It is just a quick and neither complete nor sound way to get information on where the variable originates from.
-
-This query replaces the old [\`request-lineage\`](${doc_files_1.FlowrWikiBaseRef}/Interface#message-request-lineage) message.
-
-		`;
-    }
-});
 (0, doc_query_1.registerQueryDocumentation)('dataflow-cluster', {
     name: 'Dataflow Cluster Query',
     type: 'active',
@@ -243,6 +212,25 @@ ${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
 		`;
     }
 });
+(0, doc_query_1.registerQueryDocumentation)('inspect-higher-order', {
+    name: 'Inspect Higher-Order Functions Query',
+    type: 'active',
+    shortDescription: 'Determine whether functions are higher-order functions',
+    functionName: inspect_higher_order_query_executor_1.executeHigherOrderQuery.name,
+    functionFile: '../queries/catalog/inspect-higher-order-query/inspect-higher-order-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'f <- function() function(x) x; f()';
+        return `
+With this query you can identify which functions in the code are higher-order functions, i.e., either take a function as an argument or return a function.
+Please note, that functions that are just identities (e.g., \`function(x) x\`) are not considered higher-order if they do not take a function as an argument.
+
+Using the example code \`${exampleCode}\` the following query returns the information for all identified function definitions whether they are higher-order functions:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'inspect-higher-order',
+            }], { showCode: true })}
+		`;
+    }
+});
 (0, doc_query_1.registerQueryDocumentation)('origin', {
     name: 'Origin Query',
     type: 'active',
@@ -623,7 +611,7 @@ ${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
                 type: 'location-map'
             }], { showCode: false, collapseQuery: true })}
 
-All locations are given as a ${(0, doc_types_1.shortLink)('SourceRange', types.info)} paired with the file id in the format \`[file-id, [start-line, start-column, end-line, end-column]]\`.	
+All locations are given as a ${(0, doc_types_1.shortLink)('SourceRange', types.info)} paired with the file id in the format \`[file-id, [start-line, start-column, end-line, end-column]]\`.
 
 		`;
     }
@@ -640,7 +628,9 @@ ${(0, doc_structure_1.block)({
         content: `
 There are many ways to query a dataflow graph created by flowR.
 For example, you can use the [\`request-query\`](${doc_files_1.FlowrWikiBaseRef}/Interface#message-request-query) message
-with a running flowR server, or the ${(0, doc_cli_option_1.getReplCommand)('query')} command in the flowR [REPL](${doc_files_1.FlowrWikiBaseRef}/Interface#repl).	
+with a running flowR server, or the ${(0, doc_cli_option_1.getReplCommand)('query')} command in the flowR [REPL](${doc_files_1.FlowrWikiBaseRef}/Interface#repl).
+
+Also, check out the [${doc_files_1.FlowrGithubGroupName}/sample-analyzer-project-query](${doc_files_1.FlowrGithubBaseRef}/sample-analyzer-project-query) repository for a complete example project using the query API.
 			`.trim()
     })}
 

package/documentation/print-readme.js

@@ -15,6 +15,104 @@ 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");
+const doc_issue_1 = require("./doc-util/doc-issue");
+const strings_1 = require("../util/text/strings");
+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';
+}
 async function getText(shell) {
     const dateOptions = { year: 'numeric', month: 'short', day: 'numeric' };
     return `
@@ -155,6 +253,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.
@@ -167,7 +272,7 @@ We welcome every contribution! Please check out the [developer onboarding](${doc
 
 ----
 
-*flowr* is actively developed by [Florian Sihler](https://eagleoutice.github.io/portfolio/) under the
+*flowr* is actively developed by [Florian Sihler](https://eagleoutice.github.io/portfolio/) and (since October 1st 2025) [Oliver Gerstl](https://www.linkedin.com/in/oliver-gerstl) 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").
 

package/engines.d.ts

@@ -1,4 +1,4 @@
-import type { FlowrConfigOptions, KnownEngines } from './config';
+import { type FlowrConfigOptions, type KnownEngines } from './config';
 /**
  * Retrieve all requested engine instance.
  * Please make sure that if this includes the R engine, that you properly shut it down again!

package/linter/linter-executor.d.ts

@@ -1,5 +1,8 @@
-import type { LintingRuleConfig, LintingRuleNames } from './linter-rules';
+import { type LintingRuleConfig, type LintingRuleNames } from './linter-rules';
 import type { LintingResults } from './linter-format';
 import type { DeepPartial } from 'ts-essentials';
-import type { FlowrAnalysisProvider } from '../project/flowr-analyzer';
-export declare function executeLintingRule<Name extends LintingRuleNames>(ruleName: Name, input: FlowrAnalysisProvider, lintingRuleConfig?: DeepPartial<LintingRuleConfig<Name>>): Promise<LintingResults<Name>>;
+import type { ReadonlyFlowrAnalysisProvider } from '../project/flowr-analyzer';
+/**
+ * Executes a specific linting rule on the given analysis provider input.
+ */
+export declare function executeLintingRule<Name extends LintingRuleNames>(ruleName: Name, input: ReadonlyFlowrAnalysisProvider, lintingRuleConfig?: DeepPartial<LintingRuleConfig<Name>>): Promise<LintingResults<Name>>;

package/linter/linter-executor.js

@@ -4,6 +4,9 @@ exports.executeLintingRule = executeLintingRule;
 const linter_rules_1 = require("./linter-rules");
 const flowr_search_executor_1 = require("../search/flowr-search-executor");
 const objects_1 = require("../util/objects");
+/**
+ * Executes a specific linting rule on the given analysis provider input.
+ */
 async function executeLintingRule(ruleName, input, lintingRuleConfig) {
     try {
         const rule = linter_rules_1.LintingRules[ruleName];

package/linter/linter-format.d.ts

@@ -117,7 +117,15 @@ export interface LintingResultsSuccess<Name extends LintingRuleNames> {
         readonly processTimeMs: number;
     };
 }
+/**
+ * Checks whether the given linting results represent an error.
+ * @see {@link isLintingResultsSuccess}
+ */
 export declare function isLintingResultsError<Name extends LintingRuleNames>(o: LintingResults<Name>): o is LintingResultsError;
+/**
+ * Checks whether the given linting results represent a successful linting result.
+ * @see {@link isLintingResultsError}
+ */
 export declare function isLintingResultsSuccess<Name extends LintingRuleNames>(o: LintingResults<Name>): o is LintingResultsSuccess<Name>;
 export type LintingResults<Name extends LintingRuleNames> = LintingResultsSuccess<Name> | LintingResultsError;
 export declare enum LintingResultCertainty {

package/linter/linter-format.js

@@ -3,9 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LintingPrettyPrintContext = exports.LintingRuleCertainty = exports.LintingResultCertainty = void 0;
 exports.isLintingResultsError = isLintingResultsError;
 exports.isLintingResultsSuccess = isLintingResultsSuccess;
+/**
+ * Checks whether the given linting results represent an error.
+ * @see {@link isLintingResultsSuccess}
+ */
 function isLintingResultsError(o) {
     return 'error' in o;
 }
+/**
+ * Checks whether the given linting results represent a successful linting result.
+ * @see {@link isLintingResultsError}
+ */
 function isLintingResultsSuccess(o) {
     return 'results' in o;
 }

package/linter/rules/absolute-path.d.ts

@@ -1,7 +1,6 @@
-import type { LintingResult } from '../linter-format';
-import { LintingRuleCertainty } from '../linter-format';
-import type { MergeableRecord } from '../../util/objects';
-import type { SourceRange } from '../../util/range';
+import { type LintingResult, LintingRuleCertainty } from '../linter-format';
+import { type MergeableRecord } from '../../util/objects';
+import { type SourceRange } from '../../util/range';
 import { LintingRuleTag } from '../linter-tags';
 import type { FunctionInfo } from '../../queries/catalog/dependencies-query/function-info/function-info';
 import type { FlowrConfigOptions } from '../../config';