@eagleoutice/flowr 2.2.2 → 2.2.4

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

@@ -13,13 +13,15 @@ const resolve_graph_1 = require("../../dataflow/graph/resolve-graph");
 const diff_1 = require("../../dataflow/graph/diff");
 const assert_1 = require("../../util/assert");
 const time_1 = require("../../util/time");
-function printDfGraph(graph, mark) {
+const doc_files_1 = require("./doc-files");
+function printDfGraph(graph, mark, simplified = false) {
     return `
 \`\`\`mermaid
 ${(0, dfg_1.graphToMermaid)({
         graph,
         prefix: 'flowchart LR',
-        mark
+        mark,
+        simplified
     }).string}
 \`\`\`
 	`;
@@ -32,18 +34,18 @@ function formatSideEffect(ef) {
         return `${ef}`;
     }
 }
-async function printDfGraphForCode(shell, code, { mark, showCode = true, codeOpen = false, exposeResult, switchCodeAndGraph = false } = {}) {
+async function printDfGraphForCode(parser, code, { simplified = false, mark, showCode = true, codeOpen = false, exposeResult, switchCodeAndGraph = false } = {}) {
     const now = performance.now();
-    const result = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_DATAFLOW_PIPELINE, {
-        parser: shell,
+    const result = await (0, default_pipelines_1.createDataflowPipeline)(parser, {
         request: (0, retriever_1.requestFromInput)(code)
     }).allRemainingSteps();
     const duration = performance.now() - now;
     if (switchCodeAndGraph) {
         (0, assert_1.guard)(showCode, 'can not switch code and graph if code is not shown');
     }
-    const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parse and normalize) within the generation environment.`;
-    const dfGraph = printDfGraph(result.dataflow.graph, mark);
+    const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parse and normalize, using the [${parser.name}](${doc_files_1.FlowrWikiBaseRef}/Engines) engine) within the generation environment.`;
+    const dfGraph = printDfGraph(result.dataflow.graph, mark, simplified);
+    const simplyText = simplified ? '(simplified) ' : '';
     let resultText = '\n\n';
     if (showCode) {
         const codeText = `\`\`\`r
@@ -53,7 +55,7 @@ ${code}
         resultText += `
 <details${codeOpen ? ' open' : ''}>
 
-<summary style="color:gray">${switchCodeAndGraph ? 'Dataflow Graph of the R Code' : 'R Code of the Dataflow Graph'}</summary>
+<summary style="color:gray">${switchCodeAndGraph ? `${simplyText}Dataflow Graph of the R Code` : `R Code of the ${simplyText}Dataflow Graph`}</summary>
 
 ${metaInfo} ${mark ? `The following marks are used in the graph to highlight sub-parts (uses ids): {${[...mark].join(', ')}}.` : ''}
 We encountered ${result.dataflow.graph.unknownSideEffects.size > 0 ? 'unknown side effects (with ids: ' + [...result.dataflow.graph.unknownSideEffects].map(formatSideEffect).join(', ') + ')' : 'no unknown side effects'} during the analysis.

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

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

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

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

package/documentation/doc-util/doc-normalized-ast.d.ts

@@ -1,11 +1,12 @@
 import type { DataflowGraph } from '../../dataflow/graph/graph';
 import type { RShell } from '../../r-bridge/shell';
 import type { RNodeWithParent } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { KnownParser } from '../../r-bridge/parser';
 export declare function printNormalizedAst(ast: RNodeWithParent, prefix?: string): string;
 export interface PrintNormalizedAstOptions {
     readonly showCode?: boolean;
     readonly prefix?: string;
 }
-export declare function printNormalizedAstForCode(shell: RShell, code: string, { showCode, prefix }?: PrintNormalizedAstOptions): Promise<string>;
+export declare function printNormalizedAstForCode(parser: KnownParser, code: string, { showCode, prefix }?: PrintNormalizedAstOptions): Promise<string>;
 /** returns resolved expected df graph */
 export declare function verifyExpectedSubgraph(shell: RShell, code: string, expectedSubgraph: DataflowGraph): Promise<DataflowGraph>;

package/documentation/doc-util/doc-normalized-ast.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.printNormalizedAst = printNormalizedAst;
 exports.printNormalizedAstForCode = printNormalizedAstForCode;
 exports.verifyExpectedSubgraph = verifyExpectedSubgraph;
-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");
 const decorate_1 = require("../../r-bridge/lang-4.x/ast/model/processing/decorate");
@@ -12,6 +11,7 @@ const diff_1 = require("../../dataflow/graph/diff");
 const assert_1 = require("../../util/assert");
 const ast_1 = require("../../util/mermaid/ast");
 const time_1 = require("../../util/time");
+const doc_files_1 = require("./doc-files");
 function printNormalizedAst(ast, prefix = 'flowchart TD\n') {
     return `
 \`\`\`mermaid
@@ -19,14 +19,13 @@ ${(0, ast_1.normalizedAstToMermaid)(ast, prefix)}
 \`\`\`
 	`;
 }
-async function printNormalizedAstForCode(shell, code, { showCode = true, prefix = 'flowchart TD\n' } = {}) {
+async function printNormalizedAstForCode(parser, code, { showCode = true, prefix = 'flowchart TD\n' } = {}) {
     const now = performance.now();
-    const result = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_NORMALIZE_PIPELINE, {
-        parser: shell,
+    const result = await (0, default_pipelines_1.createNormalizePipeline)(parser, {
         request: (0, retriever_1.requestFromInput)(code)
     }).allRemainingSteps();
     const duration = performance.now() - now;
-    const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parsing with the R shell) within the generation environment.`;
+    const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parsing with the [${parser.name}](${doc_files_1.FlowrWikiBaseRef}/Engines) engine) within the generation environment.`;
     return '\n\n' + printNormalizedAst(result.normalize.ast, prefix) + (showCode ? `
 <details>
 

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

@@ -1,13 +1,17 @@
-import type { RShell } from '../../r-bridge/shell';
+import type { KnownParser } from '../../r-bridge/parser';
 export declare function printReplHelpAsMarkdownTable(): string;
 export interface DocumentReplSessionOptions {
     /** defaults to false and shows starting the repl */
     hideEntry?: boolean;
     /** defaults to false and allows access to the R session */
     allowRSessionAccess?: boolean;
+    /** defaults to false and opens the details section by default */
+    openOutput?: boolean;
+    /** additional arguments to pass to the repl */
+    args?: string;
 }
 export interface DocumentReplCommand {
     command: string;
     description: string;
 }
-export declare function documentReplSession(shell: RShell, commands: readonly DocumentReplCommand[], options?: DocumentReplSessionOptions): Promise<string>;
+export declare function documentReplSession(parser: KnownParser, commands: readonly DocumentReplCommand[], options?: DocumentReplSessionOptions): Promise<string>;

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

@@ -10,6 +10,7 @@ const ansi_1 = require("../../util/ansi");
 const doc_docker_1 = require("./doc-docker");
 const prompt_1 = require("../../cli/repl/prompt");
 const doc_code_1 = require("./doc-code");
+const print_version_1 = require("../../cli/repl/print-version");
 function printHelpForScript(script, starredVersion) {
     let base = `| **${(0, doc_cli_option_1.getReplCommand)(script[0], false, starredVersion !== undefined)}** | ${script[1].description}`;
     if (starredVersion) {
@@ -37,7 +38,7 @@ function printReplHelpAsMarkdownTable() {
 ${scriptHelp.sort().join('\n')}
 `;
 }
-async function documentReplSession(shell, commands, options) {
+async function documentReplSession(parser, commands, options) {
     const collect = [];
     for (const command of commands) {
         const entry = { command, lines: [] };
@@ -50,11 +51,14 @@ async function documentReplSession(shell, commands, options) {
                 entry.lines.push(msg);
             }
         };
-        await (0, core_1.replProcessAnswer)(collectingOutput, command.command, shell, options?.allowRSessionAccess ?? false);
+        await (0, core_1.replProcessAnswer)(collectingOutput, command.command, parser, options?.allowRSessionAccess ?? false);
         collect.push(entry);
     }
     let result = '';
-    let cache = options?.hideEntry ? '' : `docker run -it --rm ${doc_docker_1.DockerName}\n`;
+    let cache = options?.hideEntry ? '' : `$ docker run -it --rm ${doc_docker_1.DockerName} ${options?.args ? options?.args + ' ' : ''}# or npm run flowr ${options?.args ? '-- ' + options?.args : ''}\n`;
+    if (!options?.hideEntry) {
+        cache += await (0, print_version_1.versionReplString)(parser) + '\n';
+    }
     for (const { command, lines } of collect) {
         if (lines.length === 0) {
             cache += prompt_1.rawPrompt + ' ' + command.command + '\n';
@@ -62,13 +66,13 @@ async function documentReplSession(shell, commands, options) {
         }
         result += `
 ${(0, doc_code_1.codeBlock)('shell', cache + prompt_1.rawPrompt + ' ' + command.command)}
-<details>
+<details${options?.openOutput ? ' open' : ''}>
 <summary style='color:gray'>Output</summary>
 
-${command.description}
-
 ${(0, doc_code_1.codeBlock)('text', lines.join('\n'))}
 
+${command.description}
+
 </details>
 
 `;

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

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

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

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

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

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

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

@@ -25,22 +25,25 @@ export interface MermaidTypeReport {
     program: ts.Program;
 }
 export declare function getTypesFromFolderAsMermaid(options: GetTypesAsMermaidOption): MermaidTypeReport;
-export declare function implSnippet(node: TypeElementInSource | undefined, program: ts.Program, showName?: boolean, nesting?: number): string;
+export declare function implSnippet(node: TypeElementInSource | undefined, program: ts.Program, showName?: boolean, nesting?: number, open?: boolean): string;
 export interface PrintHierarchyArguments {
     readonly program: ts.Program;
-    readonly hierarchy: TypeElementInSource[];
+    readonly info: TypeElementInSource[];
     readonly root: string;
     readonly collapseFromNesting?: number;
     readonly initialNesting?: number;
     readonly maxDepth?: number;
+    readonly openTop?: boolean;
 }
 export declare const mermaidHide: string[];
-export declare function printHierarchy({ program, hierarchy, root, collapseFromNesting, initialNesting, maxDepth }: PrintHierarchyArguments): string;
+export declare function printHierarchy({ program, info, root, collapseFromNesting, initialNesting, maxDepth, openTop }: PrintHierarchyArguments): string;
 /**
  * Create a short link to a type in the documentation
- * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g. `MyContainer::MyType` (this works with function nestings too)
+ * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
+ *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
  * @param hierarchy - The hierarchy of types to search in
  * @param codeStyle - Whether to use code style for the link
+ * @param realNameWrapper - How to highlight the function in name in the `x::y` format?
  */
-export declare function shortLink(name: string, hierarchy: TypeElementInSource[], codeStyle?: boolean): string;
+export declare function shortLink(name: string, hierarchy: readonly TypeElementInSource[], codeStyle?: boolean, realNameWrapper?: string): string;
 export declare function getDocumentationForType(name: string, hierarchy: TypeElementInSource[]): string;

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

@@ -218,7 +218,7 @@ function collectHierarchyInformation(sourceFiles, options) {
     return hierarchyList;
 }
 function getTypePathLink({ filePath, lineNumber }, prefix = doc_files_1.RemoteFlowrFilePathBaseRef) {
-    const fromSource = filePath.replace(/^.*\/src\//, 'src/');
+    const fromSource = filePath.replace(/^.*\/src\//, 'src/').replace(/^.*\/test\//, 'test/');
     return `${prefix}/${fromSource}#L${lineNumber}`;
 }
 function generateMermaidClassDiagram(hierarchyList, rootName, options, visited = new Set()) {
@@ -305,33 +305,36 @@ function getTypesFromFolderAsMermaid(options) {
     }
     return getTypesFromFileAsMermaid(files, options);
 }
-function implSnippet(node, program, showName = true, nesting = 0) {
+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);
     const bold = node.kind === 'interface' || node.kind === 'enum' ? '**' : '';
     const sep = node.comments ? '  \n' : '\n';
     let text = node.comments?.join('\n') ?? '';
+    if (text.trim() !== '') {
+        text = '  ' + text;
+    }
     const code = node.node.getFullText(program.getSourceFile(node.node.getSourceFile().fileName));
-    text += `\n${indent}<details><summary style="color:gray">Defined at <a href="${getTypePathLink(node)}">${getTypePathLink(node, '.')}</a></summary>\n\n${(0, doc_code_1.codeBlock)('ts', code)}\n\n</details>\n`;
+    text += `\n<details${open ? ' open' : ''}><summary style="color:gray">Defined at <a href="${getTypePathLink(node)}">${getTypePathLink(node, '.')}</a></summary>\n\n${(0, doc_code_1.codeBlock)('ts', code)}\n\n</details>\n`;
     const init = showName ? `* ${bold}[${node.name}](${getTypePathLink(node)})${bold} ${sep}${indent}` : '';
     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, hierarchy, root, collapseFromNesting = 1, initialNesting = 0, maxDepth = 20 }) {
+function printHierarchy({ program, info, root, collapseFromNesting = 1, initialNesting = 0, maxDepth = 20, openTop }) {
     if (initialNesting > maxDepth) {
         return '';
     }
-    const node = hierarchy.find(e => e.name === root);
+    const node = info.find(e => e.name === root);
     if (!node) {
         return '';
     }
-    const thisLine = implSnippet(node, program, true, initialNesting);
+    const thisLine = implSnippet(node, program, true, initialNesting, initialNesting === 0 && openTop);
     const result = [];
     for (const baseType of node.extends) {
         if (exports.mermaidHide.includes(baseType)) {
             continue;
         }
-        const res = printHierarchy({ program, hierarchy, root: baseType, collapseFromNesting, initialNesting: initialNesting + 1, maxDepth });
+        const res = printHierarchy({ program, info: info, root: baseType, collapseFromNesting, initialNesting: initialNesting + 1, maxDepth });
         result.push(res);
     }
     const out = result.join('\n');
@@ -345,32 +348,42 @@ function printHierarchy({ program, hierarchy, root, collapseFromNesting = 1, ini
 function retrieveNode(name, hierarchy) {
     let container = undefined;
     if (name.includes('::')) {
-        [container, name] = name.split('::');
+        [container, name] = name.split(/:::?/);
     }
-    const node = hierarchy.find(e => e.name === name);
-    if (!node) {
+    let node = hierarchy.filter(e => e.name === name);
+    if (node.length === 0) {
         return undefined;
     }
-    else if (container && !node.extends.includes(container)) {
-        return undefined;
+    else if (container) {
+        node = node.filter(n => n.extends.includes(container));
+        if (node.length === 0) {
+            return undefined;
+        }
     }
-    return [container, name, node];
+    return [container, name, node[0]];
 }
 /**
  * Create a short link to a type in the documentation
- * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g. `MyContainer::MyType` (this works with function nestings too)
+ * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
+ *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
  * @param hierarchy - The hierarchy of types to search in
  * @param codeStyle - Whether to use code style for the link
+ * @param realNameWrapper - How to highlight the function in name in the `x::y` format?
  */
-function shortLink(name, hierarchy, codeStyle = true) {
+function shortLink(name, hierarchy, codeStyle = true, realNameWrapper = 'b') {
     const res = retrieveNode(name, hierarchy);
     if (!res) {
+        console.error(`Could not find node ${name} when resolving short link!`);
         return '';
     }
-    const [pkg, mainName, node] = res;
-    const comments = node.comments?.join('\n').replace(/\\?\n|```[a-zA-Z]*|\s\s*/g, ' ').replace(/<\/?code>|`/g, '').replace(/"/g, '\'') ?? '';
+    const [, mainName, node] = res;
+    let pkg = res[0];
+    if (name.includes(':::')) {
+        pkg = undefined;
+    }
+    const comments = node.comments?.join('\n').replace(/\\?\n|```[a-zA-Z]*|\s\s*/g, ' ').replace(/<\/?code>|`/g, '').replace(/<\/?p\/?>/g, ' ').replace(/"/g, '\'') ?? '';
     return `[${codeStyle ? '<code>' : ''}${(node.comments?.length ?? 0) > 0 ?
-        (0, html_hover_over_1.textWithTooltip)(pkg ? `${pkg}::<b>${mainName}</b>` : mainName, comments.length > 400 ? comments.slice(0, 400) + '...' : comments) : node.name}${codeStyle ? '</code>' : ''}](${getTypePathLink(node)})`;
+        (0, html_hover_over_1.textWithTooltip)(pkg ? `${pkg}::<${realNameWrapper}>${mainName}</${realNameWrapper}>` : mainName, comments.length > 400 ? comments.slice(0, 400) + '...' : comments) : node.name}${codeStyle ? '</code>' : ''}](${getTypePathLink(node)})`;
 }
 function getDocumentationForType(name, hierarchy) {
     const res = retrieveNode(name, hierarchy);

package/documentation/index.d.ts

@@ -0,0 +1,9 @@
+export * from './print-core-wiki';
+export * from './print-query-wiki';
+export * from './print-search-wiki';
+export * from './print-engines-wiki';
+export * from './print-interface-wiki';
+export * from './print-dataflow-graph-wiki';
+export * from './print-normalized-ast-wiki';
+export * from './print-capabilities-markdown';
+export * from './print-linting-and-testing-wiki';

package/documentation/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./print-core-wiki"), exports);
+__exportStar(require("./print-query-wiki"), exports);
+__exportStar(require("./print-search-wiki"), exports);
+__exportStar(require("./print-engines-wiki"), exports);
+__exportStar(require("./print-interface-wiki"), exports);
+__exportStar(require("./print-dataflow-graph-wiki"), exports);
+__exportStar(require("./print-normalized-ast-wiki"), exports);
+__exportStar(require("./print-capabilities-markdown"), exports);
+__exportStar(require("./print-linting-and-testing-wiki"), exports);
+//# sourceMappingURL=index.js.map

package/documentation/print-capabilities-markdown.js

@@ -1,18 +1,81 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const data_1 = require("../r-bridge/data/data");
-const version_1 = require("../util/version");
 const log_1 = require("../../test/functionality/_helper/log");
+const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
+const strings_1 = require("../util/strings");
+const doc_general_1 = require("./doc-util/doc-general");
+const tree_sitter_executor_1 = require("../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor");
+const fs_1 = __importDefault(require("fs"));
+const doc_structure_1 = require("./doc-util/doc-structure");
+const detailedInfoFile = 'coverage/flowr-test-details.json';
+function obtainDetailedInfos() {
+    if (!fs_1.default.existsSync(detailedInfoFile)) {
+        return undefined;
+    }
+    const content = fs_1.default.readFileSync(detailedInfoFile).toString();
+    const base = JSON.parse(content);
+    const out = new Map();
+    for (const [key, values] of base) {
+        out.set(key, values.map(v => ({
+            id: v.id,
+            name: v.name,
+            capabilities: new Set(v.capabilities),
+            context: new Set(v.context)
+        })));
+    }
+    return out;
+}
 const supportedSymbolMap = new Map([
-    ['not', ':red_circle:'],
-    ['partially', ':large_orange_diamond:'],
-    ['fully', ':green_square:']
+    ['not', '🔴'],
+    ['partially', '🔶'],
+    ['fully', '🟩']
 ]);
-function printSingleCapability(depth, index, capability) {
+function getTestDetails(info, capability) {
+    if (!info.info) {
+        return '';
+    }
+    const totalTests = info.info.get(capability.id);
+    const uniqueTests = totalTests?.filter((v, i, a) => a.findIndex(t => t.id === v.id) === i);
+    if (!uniqueTests || uniqueTests.length === 0) {
+        return '';
+    }
+    const grouped = new Map();
+    for (const { context } of uniqueTests) {
+        for (const c of context) {
+            grouped.set(c, (grouped.get(c) ?? 0) + 1);
+        }
+    }
+    if (grouped.get('desugar-tree-sitter') !== undefined && grouped.get('desugar-tree-sitter') === grouped.get('desugar-shell')) {
+        grouped.set('desugar', grouped.get('desugar-tree-sitter') ?? 0);
+        grouped.delete('desugar-shell');
+        grouped.delete('desugar-tree-sitter');
+    }
+    grouped.delete('other'); // opinionated view on the categories
+    const output = grouped.get('output');
+    grouped.delete('output');
+    const testString = [`${uniqueTests.length} test${uniqueTests.length !== 1 ? 's' : ''}`];
+    // sort by count
+    const sorted = [...grouped.entries()].sort((a, b) => b[1] - a[1]);
+    for (const [context, count] of sorted) {
+        testString.push(`${context}: ${count}`);
+    }
+    if (output) {
+        testString.push(`and backed with output: ${output}`);
+    }
+    return ` (${testString.join(', ')})`;
+}
+function escapeId(id) {
+    return id.replace(/[^a-zA-Z0-9]/g, '_');
+}
+async function printSingleCapability(info, depth, index, capability) {
     const indent = '    '.repeat(depth);
     const indexStr = index.toString().padStart(2, ' ');
     const nextLineIndent = '  '.repeat(depth + indexStr.length);
-    const mainLine = `${indent}${indexStr}. **${capability.name}** (<a id='${capability.id}'>\`${capability.id}\`</a>)`;
+    const mainLine = `${indent}${indexStr}. <a id='${capability.id}'></a>**${capability.name}** <a href="#${escapeId(capability.id)}">🔗</a>${getTestDetails(info, capability)}`;
     let nextLine = '';
     if (capability.supported) {
         nextLine += `${supportedSymbolMap.get(capability.supported)} `;
@@ -20,43 +83,66 @@ function printSingleCapability(depth, index, capability) {
     if (capability.description) {
         nextLine += capability.description;
     }
-    if (capability.note) {
-        nextLine += `\\\n${nextLineIndent}_${capability.note}_`;
+    if (capability.url) {
+        nextLine += '\\\nSee ' + (0, strings_1.joinWithLast)(capability.url.map(({ name, href }) => `[${name}](${href})`)) + ' for more info.';
+    }
+    nextLine += ' Internal ID: `' + capability.id + '`';
+    if (capability.example) {
+        nextLine += `\n${(0, doc_general_1.prefixLines)(typeof capability.example === 'string' ? capability.example : await capability.example(info.parser), nextLineIndent + '> ')}`;
     }
     return nextLine ? `${mainLine}\\\n${nextLineIndent}${nextLine}` : mainLine;
 }
-function printAsMarkdown(capabilities, depth = 0, lines = []) {
+async function printAsMarkdown(info, capabilities, depth = 0, lines = []) {
     for (let i = 0; i < capabilities.length; i++) {
         const capability = capabilities[i];
-        const result = printSingleCapability(depth, i + 1, capability);
+        const result = await printSingleCapability(info, depth, i + 1, capability);
         lines.push(result);
         if (capability.capabilities) {
-            printAsMarkdown(capability.capabilities, depth + 1, lines);
+            await printAsMarkdown(info, capability.capabilities, depth + 1, lines);
         }
     }
     return lines.join('\n');
 }
 function getPreamble() {
-    const currentDateAndTime = new Date().toISOString().replace('T', ', ').replace(/\.\d+Z$/, ' UTC');
-    const shortenFilename = module.filename.replace(/^.*src\//, 'src/');
-    return `_This document was generated from '${shortenFilename}' on ${currentDateAndTime} summarizing flowR's current capabilities (v${(0, version_1.flowrVersion)().format()})._
+    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'current capabilities' })}
 
-The code-font behind each capability name is a link to the capability's id. This id can be used to reference the capability in a labeled test within flowR.
+Each capability has an id that can be used to link to it (use the link symbol to get a direct link to the capability).
+The internal id is also mentioned in the capability description. This id can be used to reference the capability in a labeled test within flowR.
 Besides, we use colored bullets like this:
 
 | <!-- -->               | <!-- -->                                              |
 | ---------------------- | ----------------------------------------------------- |
-| :green_square:         | _flowR_ is capable of handling this feature fully     |
-| :large_orange_diamond: | _flowR_ is capable of handling this feature partially |
-| :red_circle:           | _flowR_ is not capable of handling this feature       |
+| ${supportedSymbolMap.get('fully')} | _flowR_ is capable of handling this feature _fully_     |
+| ${supportedSymbolMap.get('partially')} | _flowR_ is capable of handling this feature _partially_ |
+| ${supportedSymbolMap.get('not')} | _flowR_ is _not_ capable of handling this feature     |
 
 :cloud: This could be a feature diagram... :cloud:
 
+${(0, doc_structure_1.block)({
+        type: 'NOTE',
+        content: `
+The capabilities are a qualitative measure of the features that flowR can handle.
+Statements like "flowR can fully handle 50/80 capabilities" are discouraged as the capabilities may have a vastly different granularity.
+Please prefer using a statement like "flowR has only partial support for feature 'XY'" (or simply reference this document) within the flowR sources.
+	`
+    })}
 `;
 }
+async function print(parser) {
+    /* check if the detailed test data is available */
+    if (!fs_1.default.existsSync(detailedInfoFile)) {
+        console.warn('\x1b[31mNo detailed test data available. Run the full tests (npm run test-full) to generate it.\x1b[m');
+    }
+    return getPreamble() + await printAsMarkdown({ parser, info: obtainDetailedInfos() }, data_1.flowrCapabilities.capabilities);
+}
 /** if we run this script, we want a Markdown representation of the capabilities */
 if (require.main === module) {
     (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
-    console.log(getPreamble() + printAsMarkdown(data_1.flowrCapabilities.capabilities));
+    void tree_sitter_executor_1.TreeSitterExecutor.initTreeSitter().then(() => {
+        const parser = new tree_sitter_executor_1.TreeSitterExecutor();
+        void print(parser).then(str => {
+            console.log(str);
+        });
+    });
 }
 //# sourceMappingURL=print-capabilities-markdown.js.map

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

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