@eagleoutice/flowr 2.0.25 → 2.1.0

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

@@ -0,0 +1,508 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.documentAllMessages = documentAllMessages;
+const doc_server_message_1 = require("../../doc-util/doc-server-message");
+const message_hello_1 = require("../../../cli/repl/server/messages/message-hello");
+const shell_1 = require("../../../r-bridge/shell");
+const doc_docker_1 = require("../../doc-util/doc-docker");
+const doc_cli_option_1 = require("../../doc-util/doc-cli-option");
+const doc_code_1 = require("../../doc-util/doc-code");
+const message_analysis_1 = require("../../../cli/repl/server/messages/message-analysis");
+const doc_files_1 = require("../../doc-util/doc-files");
+const cfg_1 = require("../../../util/mermaid/cfg");
+const doc_cfg_1 = require("../../doc-util/doc-cfg");
+const doc_issue_1 = require("../../doc-util/doc-issue");
+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 call_context_query_format_1 = require("../../../queries/call-context-query/call-context-query-format");
+const message_lineage_1 = require("../../../cli/repl/server/messages/message-lineage");
+function documentAllMessages() {
+    (0, doc_server_message_1.documentServerMessage)({
+        title: 'Hello',
+        type: 'response',
+        definitionPath: '../cli/repl/server/messages/message-hello.ts',
+        defResponse: message_hello_1.helloMessageDefinition,
+        mermaidSequenceDiagram: `
+    Client-->Server: connects
+    Server->>Client: hello
+	`,
+        shortDescription: 'The server informs the client about the successful connection and provides Meta-Information.',
+        text: async (shell) => {
+            return `
+	
+After launching _flowR_, for example, with <code>docker run -it --rm ${doc_docker_1.DockerName} ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'server', false, false)}</code>&nbsp;(🐳️), simply connecting should present you with a \`${message_hello_1.helloMessageDefinition.type}\` message, that amongst others should reveal the versions of&nbsp;_flowR_ and&nbsp;R, using the [semver 2.0](https://semver.org/spec/v2.0.0.html) versioning scheme.
+The message looks like this:
+
+${(0, doc_code_1.codeBlock)('json', await (0, doc_server_message_1.inServerContext)(shell, socket => {
+                const [hello] = socket.getMessages(['hello']);
+                return JSON.stringify(hello, null, 2);
+            }))}
+
+There are currently a few messages that you can send after the hello message.
+If you want to _slice_ a piece of R code you first have to send an [analysis request](#message-request-file-analysis), so that you can send one or multiple slice requests afterward.
+Requests for the [REPL](#message-request-repl) are independent of that.
+	`;
+        }
+    });
+    const cfgSample = 'if(unknown > 0) { x <- 2 } else { x <- 5 }\nfor(i in 1:x) { print(x); print(i) }';
+    (0, doc_server_message_1.documentServerMessage)({
+        title: 'Analysis',
+        type: 'request',
+        definitionPath: '../cli/repl/server/messages/message-analysis.ts',
+        defRequest: message_analysis_1.requestAnalysisMessage,
+        defResponse: message_analysis_1.analysisResponseMessage,
+        mermaidSequenceDiagram: `
+    Client->>+Server: request-file-analysis
+    alt
+        Server-->>Client: response-file-analysis
+    else
+        Server-->>Client: error
+    end
+    deactivate  Server
+	`,
+        shortDescription: 'The server builds the dataflow graph for a given input file (or a set of files).',
+        text: async (shell) => {
+            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).
+
+> [!IMPORTANT]
+> 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.
+
+Furthermore, the request must contain either a \`content\` field to directly pass the file's content or a \`filepath\` field which contains the path to the file (this path must be accessible for the server to be useful).
+If you add the \`id\` field, the answer will use the same \`id\` so you can match requests and the corresponding answers.
+See the implementation of the request-file-analysis message for more information.
+
+${await (0, doc_server_message_1.documentServerMessageResponse)({
+                shell,
+                messageType: 'request-file-analysis',
+                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:`,
+                        message: {
+                            type: 'request-file-analysis',
+                            id: '1',
+                            filetoken: 'x',
+                            content: 'x <- 1\nx + 1'
+                        },
+                        mark: true
+                    },
+                    {
+                        type: 'response',
+                        expectedType: 'response-file-analysis',
+                        description: `
+
+The \`results\` field of the response effectively contains three keys of importance:
+
+- \`parse\`: which contains 1:1 the parse result in CSV format that we received from the \`${shell_1.RShell.name}\` (i.e., the AST produced by the parser of the R interpreter).
+- \`normalize\`: which contains the normalized AST, including ids (see the \`info\` field and the [Normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized%20AST) wiki page).
+- \`dataflow\`: especially important is the \`graph\` field which contains the dataflow graph as a set of root vertices (see the [Dataflow Graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph) wiki page).
+			`
+                    }
+                ]
+            })}
+
+You receive an error if, for whatever reason, the analysis fails (e.g., the message or code you sent contained syntax errors).
+It contains a human-readable description *why* the analysis failed (see the error message implementation for more details).
+
+${await (0, doc_server_message_1.documentServerMessageResponse)({
+                shell,
+                title: 'Example Error Message',
+                messages: [{
+                        type: 'request',
+                        message: {
+                            type: 'request-file-analysis',
+                            id: '1',
+                            filename: 'sample.R',
+                            content: 'x <-'
+                        }
+                    }, {
+                        type: 'response',
+                        expectedType: 'error',
+                        mark: true
+                    }]
+            })}
+
+&nbsp;
+
+<a id="analysis-include-cfg"></a>
+**Including the Control Flow Graph**
+
+While _flowR_ does (for the time being) not use an explicit control flow graph but instead relies on control-dependency edges within the dataflow graph, 
+the respective structure can still be exposed using the server (note that, as this feature is not needed within _flowR_, it is tested significantly less - 
+so please create a [new issue](${doc_issue_1.NewIssueUrl}) for any bug you may encounter).
+For this, the analysis request may add \`cfg: true\` to its list of options.
+
+${await (0, doc_server_message_1.documentServerMessageResponse)({
+                shell,
+                title: 'Requesting a Control Flow Graph',
+                messages: [{
+                        type: 'request',
+                        message: {
+                            type: 'request-file-analysis',
+                            id: '1',
+                            filetoken: 'x',
+                            content: cfgSample,
+                            cfg: true
+                        },
+                        mark: true
+                    }, {
+                        type: 'response',
+                        expectedType: 'response-file-analysis',
+                        description: `
+The response looks basically the same as a response sent without the \`cfg\` flag. However, additionally it contains a \`cfg\` field. 
+If you are interested in a visual representation of the control flow graph, see the 
+[visualization with mermaid](${await (async () => {
+                            const res = await (0, doc_cfg_1.getCfg)(shell, cfgSample);
+                            return (0, cfg_1.cfgToMermaidUrl)(res.info, res.ast);
+                        })()}).
+			`
+                    }]
+            })}
+
+&nbsp;
+
+<a id="analysis-format-n-quads"></a>
+**Retrieve the Output as RDF N-Quads**
+
+The default response is formatted as JSON.
+However, by specifying \`format: "n-quads"\`, you can retrieve the individual results (e.g., the [Normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized%20AST)),
+as [RDF N-Quads](https://www.w3.org/TR/n-quads/).
+This works with and without the control flow graph as described [above](#analysis-include-cfg).
+
+${await (0, doc_server_message_1.documentServerMessageResponse)({
+                shell,
+                title: 'Requesting RDF N-Quads',
+                messages: [{
+                        type: 'request',
+                        message: {
+                            type: 'request-file-analysis',
+                            id: '1',
+                            filetoken: 'x',
+                            content: 'x <- 1\nx + 1',
+                            format: 'n-quads',
+                            cfg: true
+                        },
+                        mark: true
+                    }, {
+                        type: 'response',
+                        expectedType: 'response-file-analysis',
+                        description: `
+Please note, that the base message format is still JSON. Only the individual results get converted. 
+While the context is derived from the \`filename\`, we currently offer no way to customize other parts of the quads 
+(please open a [new issue](${doc_issue_1.NewIssueUrl}) if you require this).
+			`
+                    }]
+            })}
+	`;
+        }
+    });
+    (0, doc_server_message_1.documentServerMessage)({
+        title: 'Slice',
+        type: 'request',
+        definitionPath: '../cli/repl/server/messages/message-slice.ts',
+        defRequest: message_slice_1.requestSliceMessage,
+        defResponse: message_slice_1.responseSliceMessage,
+        mermaidSequenceDiagram: `
+    Client->>+Server: request-slice
+
+    alt
+        Server-->>Client: response-slice
+    else
+        Server-->>Client: error
+    end
+    deactivate  Server
+	`,
+        shortDescription: 'The server slices a file based on the given criteria.',
+        text: async (shell) => {
+            return `
+To slice, 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 slice the same file.
+Besides that, you only need to add an array of slicing criteria, using one of the formats described on the [terminology wiki page](${doc_files_1.FlowrWikiBaseRef}/Terminology#slicing-criterion) 
+(however, instead of using \`;\`, you can simply pass separate array elements).
+See the implementation of the request-slice message for more information.
+
+Additionally, you may pass \`"noMagicComments": true\` to disable the automatic selection of elements based on magic comments (see below).
+
+${await (0, doc_server_message_1.documentServerMessageResponse)({
+                shell,
+                messageType: 'request-slice',
+                messages: [{
+                        type: 'request',
+                        description: `Let's assume you want to slice the following script:\n${(0, doc_code_1.codeBlock)('r', 'x <- 1\nx + 1')}\n\nFor this we first request the analysis, using a \`filetoken\` of \`x\` to slice the file in the next 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',
+                        description: 'Of course, the second slice criterion `2:1` is redundant for the input, as they refer to the same variable. It is only for demonstration purposes.',
+                        message: {
+                            type: 'request-slice',
+                            id: '2',
+                            filetoken: 'x',
+                            criterion: ['2@x', '2:1']
+                        },
+                        mark: true
+                    }, {
+                        type: 'response',
+                        expectedType: 'response-slice',
+                        description: `
+The \`results\` field of the response contains two keys of importance:
+
+- \`slice\`: which contains the result of the slicing (e.g., the ids included in the slice in \`result\`).
+- \`reconstruct\`: contains the reconstructed code, as well as additional meta information. 
+                   The automatically selected lines correspond to additional filters (e.g., magic comments) which force the unconditiojnal inclusion of certain elements.
+`
+                    }]
+            })}
+
+The semantics of the error message are similar. If, for example, the slicing criterion is invalid or the \`filetoken\` is unknown, _flowR_ will respond with an error.
+
+&nbsp;
+
+<a id="slice-magic-comments"></a>
+**Magic Comments**
+
+
+Within a document that is to be sliced, you can use magic comments to influence the slicing process:
+
+- \`# flowr@include_next_line\` will cause the next line to be included, independent of if it is important for the slice.
+- \`# flowr@include_this_line\` will cause the current line to be included, independent of if it is important for the slice.
+- \`# flowr@include_start\` and \`# flowr@include_end\` will cause the lines between them to be included, independent of if they are important for the slice. These magic comments can be nested but should appear on a separate line.
+
+	`;
+        }
+    });
+    (0, doc_server_message_1.documentServerMessage)({
+        title: 'REPL',
+        type: 'request',
+        definitionPath: '../cli/repl/server/messages/message-repl.ts',
+        defRequest: message_repl_1.requestExecuteReplExpressionMessage,
+        defResponse: message_repl_1.responseExecuteReplIntermediateMessage,
+        additionalDefs: [message_repl_1.responseExecuteReplEndMessage],
+        mermaidSequenceDiagram: `
+    Client->>+Server: request-repl-execution
+
+    alt
+        Server-->>Client: error
+    else
+
+    loop
+        Server-->>Client: response-repl-execution
+    end
+        Server-->>Client: end-repl-execution
+
+    end
+
+    deactivate  Server
+	`,
+        shortDescription: 'Access the read evaluate print loop of flowR.',
+        text: async (shell) => {
+            return `
+> [!WARNING]
+> To execute arbitrary R commands with a request, the server has to be started explicitly with ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'r-session-access')}.
+> Please be aware that this introduces a security risk.
+
+
+The REPL execution message allows to send a REPL command to receive its output. 
+For more on the REPL, see the [introduction](${doc_files_1.FlowrWikiBaseRef}/Overview#the-read-eval-print-loop-repl), or the [description below](#using-the-repl).
+You only have to pass the command you want to execute in the \`expression\` field. 
+Furthermore, you can set the \`ansi\` field to \`true\` if you are interested in output formatted using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
+We strongly recommend you to make use of the \`id\` field to link answers with requests as you can theoretically request the execution of multiple scripts at the same time, which then happens in parallel.
+
+> [!WARNING]
+> There is currently no automatic sandboxing or safeguarding against such requests. They simply execute the respective&nbsp;R code on your machine. 
+> Please be very careful (and do not use ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'r-session-access')} if you are unsure).
+
+
+The answer on such a request is different from the other messages as the \`response-repl-execution\` message may be sent multiple times. 
+This allows to better handle requests that require more time but already output intermediate results.
+You can detect the end of the execution by receiving the \`end-repl-execution\` message.
+
+The semantics of the error message are similar to that of the other messages.
+${await (0, doc_server_message_1.documentServerMessageResponse)({
+                shell,
+                messageType: 'request-slice',
+                messages: [{
+                        type: 'request',
+                        message: {
+                            type: 'request-repl-execution',
+                            id: '1',
+                            expression: ':help',
+                        },
+                        mark: true
+                    }, {
+                        type: 'response',
+                        expectedType: 'response-repl-execution',
+                        description: msg => {
+                            return `
+The \`stream\` field (either \`stdout\` or \`stderr\`) informs you of the output's origin: either the standard output or the standard error channel. After this message follows the end marker.
+
+
+<details>
+<summary>Pretty-Printed Result</summary>
+
+${(0, doc_code_1.codeBlock)('text', msg.result)}
+
+</details>
+				`;
+                        }
+                    }, {
+                        type: 'response',
+                        expectedType: 'end-repl-execution',
+                    }]
+            })}
+	`;
+        }
+    });
+    (0, doc_server_message_1.documentServerMessage)({
+        title: 'Query',
+        type: 'request',
+        definitionPath: '../cli/repl/server/messages/message-query.ts',
+        defRequest: message_query_1.requestQueryMessage,
+        defResponse: message_query_1.responseQueryMessage,
+        mermaidSequenceDiagram: `
+    Client->>+Server: request-query
+
+    alt
+        Server-->>Client: response-query
+    else
+        Server-->>Client: error
+    end
+    deactivate  Server
+	`,
+        shortDescription: 'Query an analysis result for specific information.',
+        text: async (shell) => {
+            return `
+To send queries, you have to send an [analysis request](#message-request-file-analysis) first. The \`filetoken\` you assign is of use here as you can re-use it to repeatedly query the same file.
+This message provides direct access to _flowR_'s Query API. Please consult the [Query API documentation](${doc_files_1.FlowrWikiBaseRef}/Query%20API) for more information.
+
+${await (0, doc_server_message_1.documentServerMessageResponse)({
+                shell,
+                messageType: 'request-query',
+                messages: [{
+                        type: 'request',
+                        description: `Let's assume you want to query the following script:\n${(0, doc_code_1.codeBlock)('r', example_query_code_1.exampleQueryCode)}.\n\nFor this we first request the analysis, using a dummy \`filetoken\` of \`x\` to slice the file in the next request.`,
+                        message: {
+                            type: 'request-file-analysis',
+                            id: '1',
+                            filetoken: 'x',
+                            content: example_query_code_1.exampleQueryCode
+                        }
+                    }, {
+                        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-query',
+                            id: '2',
+                            filetoken: 'x',
+                            query: [
+                                {
+                                    type: 'compound',
+                                    query: 'call-context',
+                                    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- otherwise we would have to carry generic typing information through the test infrastrcuture
+                                    commonArguments: {
+                                        kind: 'visualize',
+                                        subkind: 'text',
+                                        callTargets: call_context_query_format_1.CallTargets.OnlyGlobal,
+                                    },
+                                    arguments: [
+                                        {
+                                            callName: '^mean$'
+                                        },
+                                        {
+                                            callName: '^print$',
+                                            callTargets: call_context_query_format_1.CallTargets.OnlyLocal
+                                        }
+                                    ]
+                                }
+                            ]
+                        },
+                        mark: true
+                    }, {
+                        type: 'response',
+                        expectedType: 'response-query'
+                    }]
+            })}
+
+	`;
+        }
+    });
+    (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: 'Obtain the lineage of a given slicing criterion.',
+        text: async (shell) => {
+            return `
+
+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-util/doc-auto-gen.d.ts

@@ -0,0 +1,7 @@
+export interface AutoGenHeaderArguments {
+    readonly rVersion?: string;
+    readonly currentDateAndTime?: string;
+    readonly filename: string;
+    readonly purpose: string;
+}
+export declare function autoGenHeader({ rVersion, filename, purpose, currentDateAndTime }: AutoGenHeaderArguments): string;

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

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoGenHeader = autoGenHeader;
+const version_1 = require("../../util/version");
+function autoGenHeader({ rVersion, filename, purpose, currentDateAndTime = new Date().toISOString().replace('T', ', ').replace(/\.\d+Z$/, ' UTC') }) {
+    const shortenFilename = filename.replace(/^.*src\//, 'src/');
+    return `_This document was generated from '${shortenFilename}' on ${currentDateAndTime} presenting an overview of flowR's ${purpose} (v${(0, version_1.flowrVersion)().format()}${rVersion ? ', using R v' + rVersion : ''})._`;
+}
+//# sourceMappingURL=doc-auto-gen.js.map

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

@@ -0,0 +1,7 @@
+import type { ControlFlowInformation } from '../../util/cfg/cfg';
+import type { RShell } from '../../r-bridge/shell';
+import type { NormalizedAst } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
+export declare function getCfg(shell: RShell, code: string): Promise<{
+    info: ControlFlowInformation;
+    ast: NormalizedAst;
+}>;

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCfg = getCfg;
+const cfg_1 = require("../../util/cfg/cfg");
+const pipeline_executor_1 = require("../../core/pipeline-executor");
+const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
+const retriever_1 = require("../../r-bridge/retriever");
+async function getCfg(shell, code) {
+    const steps = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_NORMALIZE_PIPELINE, {
+        shell,
+        request: (0, retriever_1.requestFromInput)(code)
+    }).allRemainingSteps();
+    return {
+        info: (0, cfg_1.extractCFG)(steps.normalize),
+        ast: steps.normalize
+    };
+}
+//# sourceMappingURL=doc-cfg.js.map

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

@@ -0,0 +1,8 @@
+/** Automatically provides hover over with the documentation for these! */
+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

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCliLongOptionOf = getCliLongOptionOf;
+exports.multipleCliOptions = multipleCliOptions;
+exports.getReplCommand = getReplCommand;
+/** Automatically provides hover over with the documentation for these! */
+const scripts_info_1 = require("../../cli/common/scripts-info");
+const assert_1 = require("../../util/assert");
+const doc_hover_over_1 = require("./doc-hover-over");
+const flowr_main_options_1 = require("../../cli/flowr-main-options");
+const repl_commands_1 = require("../../cli/repl/commands/repl-commands");
+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))}.`);
+    const option = script.find(({ name }) => name === optionName);
+    (0, assert_1.guard)(option !== undefined, () => `Unknown option ${optionName}, pick one of ${JSON.stringify(script.map(o => o.name))}.`);
+    const char = quote ? '`' : '';
+    const alias = withAlias && option.alias ? ' (alias:' + (0, doc_hover_over_1.textWithTooltip)(`${char}-${option.alias}${char}`, option.description) + ')' : '';
+    const ligatureBreaker = quote ? '' : '<span/>';
+    // span ensures split even with ligatures
+    return (0, doc_hover_over_1.textWithTooltip)(`${char}-${ligatureBreaker}-${optionName}${char}`, 'Description (Command Line Argument): ' + option.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];
+    (0, assert_1.guard)(commands !== undefined, () => `Unknown command ${commandName}, pick one of ${JSON.stringify(Object.keys(availableNames))}.`);
+    const char = quote ? '`' : '';
+    const aliases = commands.aliases.length > 0 ? ' (aliases: ' + commands.aliases.map(a => `:${a}`).join(', ') + ')' : '';
+    const starredComment = commandName.endsWith('*') ? ', starred version' : '';
+    const baseDescription = commandName.endsWith('*') ? '; Base Command: ' + availableNames[commandName.slice(0, -1)].description : '';
+    return (0, doc_hover_over_1.textWithTooltip)(`${char}:${commandName}${showStar ? '[*]' : ''}${char}`, `Description (Repl Command${starredComment}): ` + commands.description + baseDescription + aliases);
+}
+//# sourceMappingURL=doc-cli-option.js.map

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

@@ -0,0 +1 @@
+export declare function codeBlock(language: string, code: string | undefined): string;

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

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codeBlock = codeBlock;
+function codeBlock(language, code) {
+    return `\n\`\`\`${language}\n${code?.trim() ?? ''}\n\`\`\`\n`;
+}
+//# sourceMappingURL=doc-code.js.map

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

@@ -0,0 +1,21 @@
+import type { DataflowGraph } from '../../dataflow/graph/graph';
+import type { RShell } from '../../r-bridge/shell';
+import type { MermaidMarkdownMark } from '../../util/mermaid/dfg';
+import { DEFAULT_DATAFLOW_PIPELINE } from '../../core/steps/pipeline/default-pipelines';
+import type { PipelineOutput } from '../../core/steps/pipeline/pipeline';
+export declare function printDfGraph(graph: DataflowGraph, mark?: ReadonlySet<MermaidMarkdownMark>): string;
+export interface PrintDataflowGraphOptions {
+    readonly mark?: ReadonlySet<MermaidMarkdownMark>;
+    readonly showCode?: boolean;
+    readonly codeOpen?: boolean;
+    readonly exposeResult?: boolean;
+    readonly switchCodeAndGraph?: boolean;
+}
+export declare function printDfGraphForCode(shell: RShell, code: string, options: PrintDataflowGraphOptions & {
+    exposeResult: true;
+}): Promise<[string, PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>]>;
+export declare function printDfGraphForCode(shell: RShell, code: string, options?: PrintDataflowGraphOptions & {
+    exposeResult?: false | undefined;
+}): Promise<string>;
+/** returns resolved expected df graph */
+export declare function verifyExpectedSubgraph(shell: RShell, code: string, expectedSubgraph: DataflowGraph): Promise<DataflowGraph>;