@eagleoutice/flowr 2.6.0 → 2.6.2

package/dataflow/processor.js

@@ -10,7 +10,6 @@ exports.processDataflowFor = processDataflowFor;
  * <p>
  * Now this method can be called recursively within the other processors to parse the dataflow for nodes that you cannot narrow down
  * in type or context.
- *
  * @param current - The current node to start processing from
  * @param data    - The initial (/current) information to be passed down
  */

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

@@ -16,5 +16,11 @@ export interface ExplanationParameters {
     readonly code: string;
     readonly expectedSubgraph: DataflowGraph;
 }
+/**
+ *
+ */
 export declare function getAllVertices(): [string, VertexType][];
+/**
+ *
+ */
 export declare function getAllEdges(): [string, EdgeType][];

package/documentation/data/dfg/doc-data-dfg-util.js

@@ -4,9 +4,15 @@ exports.getAllVertices = getAllVertices;
 exports.getAllEdges = getAllEdges;
 const vertex_1 = require("../../../dataflow/graph/vertex");
 const edge_1 = require("../../../dataflow/graph/edge");
+/**
+ *
+ */
 function getAllVertices() {
     return Object.entries(vertex_1.VertexType);
 }
+/**
+ *
+ */
 function getAllEdges() {
     return Object.entries(edge_1.EdgeType).filter(([, v]) => Number.isInteger(v));
 }

package/documentation/data/faq/faqs.d.ts

@@ -0,0 +1,5 @@
+import { FaqStore } from './wiki-faq-store';
+/**
+ *
+ */
+export declare function registerFaqs(): FaqStore;

package/documentation/data/faq/faqs.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFaqs = registerFaqs;
+const wiki_faq_store_1 = require("./wiki-faq-store");
+const doc_files_1 = require("../../doc-util/doc-files");
+const doc_code_1 = require("../../doc-util/doc-code");
+/**
+ *
+ */
+function registerFaqs() {
+    const wikiFaq = new wiki_faq_store_1.FaqStore();
+    wikiFaq.withTopic('flowr.development')
+        .addFaq('What are *test labels*?', `
+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).
+`)
+        .addFaq('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 also watches the source files for changes.
+	In case of a change, this mode automatically recompiles.
+	Please note, that this may have negative performance implications (so do not use this for e.g., benchmarking).
+`)
+        .addFaq('How to 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')}
+`)
+        .addFaq('How to 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.
+`)
+        .addFaq('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')}
+`)
+        .addFaq('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*.
+`);
+    wikiFaq.withTopic('flowr.use')
+        .addFaq('How to *query* an R project?', `
+For this you can use flowR's [Query API](${doc_files_1.FlowrWikiBaseRef}/Query-API).
+If you want to create your own project using flowR as a library, check out the 
+[${doc_files_1.FlowrGithubGroupName}/sample-analyzer-project-query](${doc_files_1.FlowrGithubBaseRef}/sample-analyzer-project-query) repository for an example project setup.
+		`);
+    wikiFaq.withTopic('r.packages')
+        .addFaq('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()\`.
+`)
+        .addFaq('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](https://rdrr.io/)
+or [rdocumentation.org](https://rdocumentation.org/). Additionally, the package documentation PDF can also
+be downloaded directly from [cran](https://cran.r-project.org/).
+`);
+    return wikiFaq;
+}
+//# sourceMappingURL=faqs.js.map

package/documentation/data/faq/wiki-faq-store.d.ts

@@ -0,0 +1,18 @@
+declare const FlowrFaqTopics: {
+    readonly 'flowr.use': "✨ Using <i>flowR</i>";
+    readonly 'flowr.development': "🧑‍💻 <i>flowR</i> Development";
+    readonly 'r.packages': "📦 R Packages";
+};
+type Topic = keyof typeof FlowrFaqTopics;
+/**
+ * Manage all questions and answers by topic.
+ */
+export declare class FaqStore {
+    private faqs;
+    private currTopic;
+    withTopic(topic: Topic): this;
+    addFaq(question: string, answer: string): this;
+    private printAllTopics;
+    toMarkdown(): string;
+}
+export {};

package/documentation/data/faq/wiki-faq-store.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FaqStore = void 0;
+const doc_structure_1 = require("../../doc-util/doc-structure");
+const defaultmap_1 = require("../../../util/collections/defaultmap");
+const assert_1 = require("../../../util/assert");
+const FlowrFaqTopics = {
+    'flowr.use': '✨ Using <i>flowR</i>',
+    'flowr.development': '🧑‍💻 <i>flowR</i> Development',
+    'r.packages': '📦 R Packages'
+};
+/**
+ * Manage all questions and answers by topic.
+ */
+class FaqStore {
+    faqs = new defaultmap_1.DefaultMap(() => []);
+    currTopic = undefined;
+    withTopic(topic) {
+        this.currTopic = topic;
+        return this;
+    }
+    addFaq(question, answer) {
+        (0, assert_1.guard)(this.currTopic !== undefined, 'Current topic is not set use withTopic first');
+        question = question.replace(/\*([^*]+)\*/g, '<b>$1</b>');
+        const store = this.faqs.get(this.currTopic);
+        if (store.find(([q]) => q === question)) {
+            throw new Error(`FAQ for question "${question}" in topic "${this.currTopic}" already exists`);
+        }
+        store.push([question, answer]);
+        return this;
+    }
+    printAllTopics(topicsRegex) {
+        const topics = Array.from(this.faqs.keys())
+            .filter(topic => topicsRegex.test(topic))
+            .sort((a, b) => a.localeCompare(b));
+        let output = '';
+        for (const topic of topics) {
+            const faqs = this.faqs.get(topic).sort(([q1], [q2]) => q1.localeCompare(q2));
+            if (faqs.length === 0) {
+                continue;
+            }
+            output += (0, doc_structure_1.section)(FlowrFaqTopics[topic], 3) + '\n\n';
+            for (const [question, answer] of faqs) {
+                output += qAndA(question, answer) + '\n\n';
+            }
+        }
+        return output;
+    }
+    toMarkdown() {
+        return `
+${(0, doc_structure_1.collapsibleToc)({
+            ['💮 *flowR* FAQ']: {
+                [FlowrFaqTopics['flowr.development']]: {},
+                [FlowrFaqTopics['flowr.use']]: {}
+            },
+            ['🇷 R FAQ']: {
+                [FlowrFaqTopics['r.packages']]: {}
+            }
+        })}
+
+${(0, doc_structure_1.section)('💮 <i>flowR</i> FAQ', 2)}
+
+${this.printAllTopics(/^flowr.*$/)}
+
+${(0, doc_structure_1.section)('🇷 R FAQ', 2)}
+
+${this.printAllTopics(/^r.*$/)}  
+		`;
+    }
+}
+exports.FaqStore = FaqStore;
+function qAndA(question, answer) {
+    return (0, doc_structure_1.details)(question.trim(), answer.trim(), { hideIfEmpty: true });
+}
+//# sourceMappingURL=wiki-faq-store.js.map

package/documentation/data/server/doc-data-server-messages.d.ts

@@ -1 +1,4 @@
+/**
+ *
+ */
 export declare function documentAllServerMessages(): void;

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.
@@ -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-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,20 @@ interface BenchmarkElementBench {
     readonly range: number;
     readonly extra: string;
 }
+/**
+ *
+ */
 export declare function loadBenchmarkData(): Promise<BenchmarkData>;
+/**
+ *
+ */
 export declare function getLatestBenchmark(suite: string): Promise<BenchmarkElement>;
+/**
+ *
+ */
 export declare function getLastBenchmarkUpdate(): Promise<number>;
+/**
+ *
+ */
 export declare function getLatestDfAnalysisTime(suite: string): Promise<number>;
 export {};

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

@@ -44,6 +44,9 @@ const path_1 = __importDefault(require("path"));
 const assert_1 = require("../../util/assert");
 const BenchmarkDataPath = path_1.default.resolve(__dirname, '..', '..', '..', 'wiki', 'stats', 'benchmark', 'data.js');
 let benchmarkData = null;
+/**
+ *
+ */
 async function loadBenchmarkData() {
     if (benchmarkData === null) {
         // provide a window object to attach to in the import
@@ -54,12 +57,18 @@ async function loadBenchmarkData() {
     }
     return benchmarkData;
 }
+/**
+ *
+ */
 async function getLatestBenchmark(suite) {
     // provide a window object to attach to in the import
     const suiteData = (await loadBenchmarkData()).entries[suite];
     (0, assert_1.guard)(suiteData, `No benchmark data for suite '${suite}' found!`);
     return suiteData.sort((a, b) => b.date - a.date)[0];
 }
+/**
+ *
+ */
 async function getLastBenchmarkUpdate() {
     return (await loadBenchmarkData()).lastUpdate;
 }
@@ -68,6 +77,9 @@ function getBenchmarkElement(bench, name) {
     (0, assert_1.guard)(element, `No benchmark data for '${name}' found!`);
     return element;
 }
+/**
+ *
+ */
 async function getLatestDfAnalysisTime(suite) {
     const elem = await getLatestBenchmark(suite);
     const [parse, normalize, analyze] = ['Retrieve AST from R code', 'Normalize R AST', 'Produce dataflow information'].map(name => getBenchmarkElement(elem, name));

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

@@ -12,6 +12,9 @@ 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");
+/**
+ * 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)
@@ -25,11 +28,17 @@ async function getCfg(parser, code, simplifications = [], useDfg = true) {
         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;

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

@@ -5,12 +5,36 @@ exports.codeInline = codeInline;
 exports.jsonWithLimit = jsonWithLimit;
 const json_1 = require("../../util/json");
 const environment_1 = require("../../dataflow/environments/environment");
+/**
+ * Produces a code block in markdown format.
+ * @example
+ * ```typescript
+ * codeBlock('ts', 'const x = 42;');
+ * // Produces:
+ * //
+ * // ```ts
+ * // const x = 42;
+ * // ```
+ * ```
+ */
 function codeBlock(language, code) {
     return `\n\`\`\`${language}\n${code?.trim() ?? ''}\n\`\`\`\n`;
 }
+/**
+ * Produces an inline code span in markdown format.
+ * @example
+ * ```typescript
+ * codeInline('const x = 42;');
+ * // Produces: `<code>const x = 42;</code>`
+ * ```
+ */
 function codeInline(code) {
     return `<code>${code}</code>`;
 }
+/**
+ * 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.
+ */
 function jsonWithLimit(object, maxLength = 5_000, tooLongText = '_As the code is pretty long, we inhibit pretty printing and syntax highlighting (JSON, hiding built-in):_') {
     const prettyPrinted = JSON.stringify(object, json_1.jsonReplacer, 2);
     return `

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

@@ -1,9 +1,12 @@
 import type { DataflowGraph, UnknownSidEffect } from '../../dataflow/graph/graph';
 import type { RShell } from '../../r-bridge/shell';
-import type { MermaidMarkdownMark } from '../../util/mermaid/dfg';
+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';
 import type { KnownParser } from '../../r-bridge/parser';
+/**
+ *
+ */
 export declare function printDfGraph(graph: DataflowGraph, mark?: ReadonlySet<MermaidMarkdownMark>, simplified?: boolean): string;
 export interface PrintDataflowGraphOptions {
     readonly mark?: ReadonlySet<MermaidMarkdownMark>;
@@ -13,6 +16,9 @@ export interface PrintDataflowGraphOptions {
     readonly switchCodeAndGraph?: boolean;
     readonly simplified?: boolean;
 }
+/**
+ *
+ */
 export declare function formatSideEffect(ef: UnknownSidEffect): string;
 export declare function printDfGraphForCode(parser: KnownParser, code: string, options: PrintDataflowGraphOptions & {
     exposeResult: true;

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

@@ -16,6 +16,9 @@ const time_1 = require("../../util/text/time");
 const doc_files_1 = require("./doc-files");
 const doc_code_1 = require("./doc-code");
 const config_1 = require("../../config");
+/**
+ *
+ */
 function printDfGraph(graph, mark, simplified = false) {
     return `
 ${(0, doc_code_1.codeBlock)('mermaid', (0, dfg_1.graphToMermaid)({
@@ -26,6 +29,9 @@ ${(0, doc_code_1.codeBlock)('mermaid', (0, dfg_1.graphToMermaid)({
     }).string)}
 	`;
 }
+/**
+ *
+ */
 function formatSideEffect(ef) {
     if (typeof ef === 'object') {
         return `${ef.id} (linked)`;
@@ -34,6 +40,9 @@ function formatSideEffect(ef) {
         return `${ef}`;
     }
 }
+/**
+ *
+ */
 async function printDfGraphForCode(parser, code, { simplified = false, mark, showCode = true, codeOpen = false, exposeResult, switchCodeAndGraph = false } = {}) {
     const now = performance.now();
     const result = await (0, default_pipelines_1.createDataflowPipeline)(parser, {

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

@@ -1,2 +1,5 @@
 import type { IEnvironment } from '../../dataflow/environments/environment';
+/**
+ *
+ */
 export declare function printEnvironmentToMarkdown(env: IEnvironment | undefined): string;

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

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printEnvironmentToMarkdown = printEnvironmentToMarkdown;
 const dfg_1 = require("../../util/mermaid/dfg");
+/**
+ *
+ */
 function printEnvironmentToMarkdown(env) {
     if (env === undefined) {
         return '?? (error)';

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

@@ -1,6 +1,5 @@
 /**
  * Escapes HTML special characters in a string.
- *
  * @param str - The string to escape
  * @returns The escaped string
  */