Merge branch 'main' of github.com:flowr-analysis/flowr

Author: EagleoutIce

.github/workflows/broken-links-and-wiki.yaml

@@ -49,6 +49,9 @@ jobs:
         # just as a time-proven safety measure
         run: git lfs checkout
 
+      - name: "⚗️ Test Suite (full, for data)"
+        run: bash .github/workflows/scripts/run-flowr-command.sh "test-full -- --allowOnly=false"
+
       - name: "🛠️ Update the Generated Wiki Pages"
         run: |
           npm ci

src/documentation/doc-util/doc-dfg.ts

@@ -3,7 +3,7 @@ import type { RShell } from '../../r-bridge/shell';
 import type { MermaidMarkdownMark } from '../../util/mermaid/dfg';
 import { graphToMermaid } from '../../util/mermaid/dfg';
 import { PipelineExecutor } from '../../core/pipeline-executor';
-import { DEFAULT_DATAFLOW_PIPELINE } from '../../core/steps/pipeline/default-pipelines';
+import { createDataflowPipeline, DEFAULT_DATAFLOW_PIPELINE } from '../../core/steps/pipeline/default-pipelines';
 import { requestFromInput } from '../../r-bridge/retriever';
 import { deterministicCountingIdGenerator } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
 import { resolveDataflowGraph } from '../../dataflow/graph/resolve-graph';
@@ -12,14 +12,17 @@ import { diffOfDataflowGraphs } from '../../dataflow/graph/diff';
 import { guard } from '../../util/assert';
 import type { PipelineOutput } from '../../core/steps/pipeline/pipeline';
 import { printAsMs } from '../../util/time';
+import type { KnownParser } from '../../r-bridge/parser';
+import { FlowrWikiBaseRef } from './doc-files';
 
-export function printDfGraph(graph: DataflowGraph, mark?: ReadonlySet<MermaidMarkdownMark>) {
+export function printDfGraph(graph: DataflowGraph, mark?: ReadonlySet<MermaidMarkdownMark>, simplified = false) {
 	return `
 \`\`\`mermaid
 ${graphToMermaid({
 		graph,
 		prefix: 'flowchart LR',
-		mark
+		mark,
+		simplified
 	}).string}
 \`\`\`
 	`;
@@ -31,6 +34,7 @@ export interface PrintDataflowGraphOptions {
 	readonly codeOpen?:           boolean;
 	readonly exposeResult?:       boolean;
 	readonly switchCodeAndGraph?: boolean;
+	readonly simplified?:         boolean;
 }
 
 export function formatSideEffect(ef: UnknownSidEffect): string {
@@ -41,12 +45,11 @@ export function formatSideEffect(ef: UnknownSidEffect): string {
 	}
 }
 
-export async function printDfGraphForCode(shell: RShell, code: string, options: PrintDataflowGraphOptions & { exposeResult: true }): Promise<[string, PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>]>;
-export async function printDfGraphForCode(shell: RShell, code: string, options?: PrintDataflowGraphOptions & { exposeResult?: false | undefined }): Promise<string>;
-export async function printDfGraphForCode(shell: RShell, code: string, { mark, showCode = true, codeOpen = false, exposeResult, switchCodeAndGraph = false }: PrintDataflowGraphOptions = {}): Promise<string | [string, PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>]> {
+export async function printDfGraphForCode(parser: KnownParser, code: string, options: PrintDataflowGraphOptions & { exposeResult: true }): Promise<[string, PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>]>;
+export async function printDfGraphForCode(parser: KnownParser, code: string, options?: PrintDataflowGraphOptions & { exposeResult?: false | undefined }): Promise<string>;
+export async function printDfGraphForCode(parser: KnownParser, code: string, { simplified = false, mark, showCode = true, codeOpen = false, exposeResult, switchCodeAndGraph = false }: PrintDataflowGraphOptions = {}): Promise<string | [string, PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>]> {
 	const now = performance.now();
-	const result = await new PipelineExecutor(DEFAULT_DATAFLOW_PIPELINE, {
-		parser:  shell,
+	const result = await createDataflowPipeline(parser, {
 		request: requestFromInput(code)
 	}).allRemainingSteps();
 	const duration = performance.now() - now;
@@ -55,8 +58,9 @@ export async function printDfGraphForCode(shell: RShell, code: string, { mark, s
 		guard(showCode, 'can not switch code and graph if code is not shown');
 	}
 
-	const metaInfo = `The analysis required _${printAsMs(duration)}_ (including parse and normalize) within the generation environment.`;
-	const dfGraph = printDfGraph(result.dataflow.graph, mark);
+	const metaInfo = `The analysis required _${printAsMs(duration)}_ (including parse and normalize, using the [${parser.name}](${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) {
@@ -67,7 +71,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.

src/documentation/print-capabilities-markdown.ts

@@ -1,20 +1,82 @@
 import type { FlowrCapability } from '../r-bridge/data/types';
 import { flowrCapabilities } from '../r-bridge/data/data';
-import { flowrVersion } from '../util/version';
 import { setMinLevelOfAllLogs } from '../../test/functionality/_helper/log';
 import { LogLevel } from '../util/log';
+import { autoGenHeader } from './doc-util/doc-auto-gen';
+import { joinWithLast } from '../util/strings';
+import { block } from './doc-util/doc-structure';
+import { prefixLines } from './doc-util/doc-general';
+import { TreeSitterExecutor } from '../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor';
+import type { KnownParser } from '../r-bridge/parser';
+import fs from 'fs';
+import type { SerializedTestLabel, TestLabel } from '../../test/functionality/_helper/label';
+
+const detailedInfoFile = 'coverage/flowr-test-details.json';
+
+interface CapabilityInformation {
+	readonly parser: KnownParser;
+	readonly info:   Map<string, TestLabel[]> | undefined
+}
+
+
+function obtainDetailedInfos(): Map<string, TestLabel[]> | undefined {
+	if(!fs.existsSync(detailedInfoFile)) {
+		return undefined;
+	}
+	const content = fs.readFileSync(detailedInfoFile).toString();
+	const base = JSON.parse(content) as [string, SerializedTestLabel[]][];
+	const out = new Map<string, TestLabel[]>();
+	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)
+		} satisfies TestLabel)));
+	}
+	return out;
+}
 
 const supportedSymbolMap: Map<string, string> = new Map([
-	['not',       ':red_circle:'          ],
-	['partially', ':large_orange_diamond:'],
-	['fully',     ':green_square:'        ]
+	['not',       '🔴' ],
+	['partially', '🔶' ],
+	['fully',     '🟩' ]
 ]);
 
-function printSingleCapability(depth: number, index: number, capability: FlowrCapability) {
+function getTestDetails(info: CapabilityInformation, capability: FlowrCapability) {
+	if(!info.info) {
+		return '';
+	}
+	const totalTests = info.info.get(capability.id);
+	if(!totalTests || totalTests.length === 0) {
+		return '';
+	}
+	const grouped = new Map<string, number>();
+	for(const { context } of totalTests) {
+		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) * 2);
+		grouped.delete('desugar-shell');
+		grouped.delete('desugar-tree-sitter');
+	}
+	grouped.delete('other'); // opinionated view on the categories
+	const testString: string[] = [`${totalTests.length} test${totalTests.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}`);
+	}
+	return ` $\\color{gray}{\\textsf{(${testString.join(', ')})}}$`;
+}
+
+async function printSingleCapability(info: CapabilityInformation, depth: number, index: number, capability: FlowrCapability): Promise<string> {
 	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="#${capability.id}">🔗</a>${getTestDetails(info, capability)}`;
 	let nextLine = '';
 
 	if(capability.supported) {
@@ -23,45 +85,63 @@ function printSingleCapability(depth: number, index: number, capability: FlowrCa
 	if(capability.description) {
 		nextLine += capability.description;
 	}
-	if(capability.note) {
-		nextLine += `\\\n${nextLineIndent}_${capability.note}_`;
+	if(capability.url) {
+		nextLine += '\\\nSee ' + joinWithLast(capability.url.map(({ name, href }) => `[${name}](${href})`)) + ' for more info.';
+	}
+	nextLine += ' Internal ID: `' + capability.id + '`';
+	if(capability.example) {
+		nextLine += `\n${nextLineIndent}${prefixLines(block({ 
+			type:    'INFO', 
+			content: typeof capability.example === 'string' ? capability.example : await capability.example(info.parser) 
+		}), nextLineIndent)}`;
 	}
 	return nextLine ? `${mainLine}\\\n${nextLineIndent}${nextLine}` : mainLine;
 }
 
-function printAsMarkdown(capabilities: readonly FlowrCapability[], depth = 0, lines: string[] = []): string {
+async function printAsMarkdown(info: CapabilityInformation, capabilities: readonly FlowrCapability[], depth = 0, lines: string[] = []): Promise<string> {
 	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(): string {
-	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${flowrVersion().format()})._
+	return `${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.
 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:
 
 `;
 }
 
+async function print(parser: KnownParser) {
+	/* check if the detailed test data is available */
+	if(!fs.existsSync(detailedInfoFile)) {
+		console.warn('No detailed test data available. Run the full tests (npm run test-full) to generate it.');
+	}
+	return getPreamble() + await printAsMarkdown({ parser, info: obtainDetailedInfos() }, flowrCapabilities.capabilities);
+}
+
 /** if we run this script, we want a Markdown representation of the capabilities */
 if(require.main === module) {
 	setMinLevelOfAllLogs(LogLevel.Fatal);
-	console.log(getPreamble() + printAsMarkdown(flowrCapabilities.capabilities));
+	void TreeSitterExecutor.initTreeSitter().then(() => {
+		const parser = new TreeSitterExecutor();
+		void print(parser).then(str => {
+			console.log(str);
+		});
+	});
 }

src/r-bridge/data/data.ts

@@ -1,13 +1,40 @@
 import type { FlowrCapabilities } from './types';
+import { FlowrGithubBaseRef } from '../../documentation/doc-util/doc-files';
+import { codeBlock } from '../../documentation/doc-util/doc-code';
+import { printDfGraphForCode } from '../../documentation/doc-util/doc-dfg';
+
+const Joiner = '/';
+const AdvancedR = (subname: string) => 'Advanced R' + Joiner + subname;
+const RLang = (subname: string) => 'R Definition' + Joiner + subname;
+const Issue = (num: number) => `${FlowrGithubBaseRef}/flowr/issues/${num}`;
+const LinkTo = (id: string, label = id) => `[${label}](#${id})`;
 
 export const flowrCapabilities = {
 	name:         'Capabilities of flowR',
 	description:  'This is an evolving representation of what started with #636 to formulate capabilities in a structured format.',
-	version:      '0.0.1',
+	version:      '0.0.2',
 	capabilities: [
 		{
-			name:         'Names and Identifiers',
-			id:           'names-and-identifiers',
+			name:        'Names and Identifiers',
+			id:          'names-and-identifiers',
+			description: 'The recognition of syntactical and non-syntactical names, including their resolutions to corresponding definitions.',
+			example:     async parser => {
+				const code = '"f" <- function(x) { get("x") } \n`y x` <- 2\nprint(`y x` + f(3))';
+				return `
+Consider the following R code:
+${codeBlock('r', code)}
+Identifiers of interest are:
+
+- The symbols \`x\` (${LinkTo('name-normal')}), \`f\` (${LinkTo('name-quoted')}), and \`\` \`y x\` \`\` (${LinkTo('name-escaped')}).
+- The function calls \`<-\`, \`function\`, \`{\`, \`get\`, \`+\`, and \`print\` (${LinkTo('function-calls')}, all given with ${LinkTo('name-normal')}).
+  Especially \`{\` is identified as a ${LinkTo('grouping')} of the ${LinkTo('function-definitions', 'function-definitions\'')} body.
+- The quoted name created by a function call \`get\` (${LinkTo('name-created')}).
+
+Besides the parameter \`x\`, which is resolved in its ${LinkTo('lexicographic-scope')}, the other identifiers are resolved in the ${LinkTo('global-scope')}.
+
+${await printDfGraphForCode(parser, code, { simplified: true })}
+			`;
+			},
 			capabilities: [
 				{
 					name:         'Form',
@@ -17,19 +44,38 @@ export const flowrCapabilities = {
 							name:        'Normal',
 							id:          'name-normal',
 							supported:   'fully',
-							description: '_Recognize constructs like `a`, `plot`, ..._'
+							description: '_Recognize symbol uses like `a`, `plot`, ..._  (i.e., "normal variables or function calls").',
+							url:         [
+								{ name: AdvancedR('Bindings'), href: 'https://adv-r.hadley.nz/names-values.html#binding-basics' },
+								{ name: RLang('Identifiers'), href: 'https://cran.r-project.org/doc/manuals/r-release/R-lang.html#Identifiers-1' }
+							]
 						},
 						{
 							name:        'Quoted',
 							id:          'name-quoted',
 							supported:   'fully',
-							description: "_Recognize `\"a\"`, `'plot'`, ..._"
+							description: "_Recognize `\"a\"`, `'plot'`, ..._ In general, R allows to envelop names in quotations to allow for special characters such as spaces in variable names. However, this only works in the context of definitions. To access these names as variables, one has to either use function such as `get` or escape the name with backticks.",
+							url:         [
+								{ name: AdvancedR('Non-Syntactic Names'), href: 'https://adv-r.hadley.nz/names-values.html#non-syntactic' }
+							]
 						},
 						{
 							name:        'Escaped',
 							id:          'name-escaped',
 							supported:   'fully',
-							description: '_Recognize `` `a` ``, `` `plot` ``, ..._'
+							description: '_Recognize `` `a` ``, `` `plot` ``, ..._',
+							url:         [
+								{ name: AdvancedR('Non-Syntactic Names'), href: 'https://adv-r.hadley.nz/names-values.html#non-syntactic' }
+							]
+						},
+						{
+							name:        'Created',
+							id:          'name-created',
+							supported:   'partially',
+							description: '_Recognize functions which resolve strings as identifiers, such as `get`, ..._',
+							url:         [
+								{ name: 'flowr#633', href: Issue(633) }
+							]
 						}
 					]
 				},
@@ -670,28 +716,28 @@ export const flowrCapabilities = {
 						{
 							name:        'S3',
 							id:          'oop-s3',
-							note:        'https://adv-r.hadley.nz/s3.html',
+							example:     'https://adv-r.hadley.nz/s3.html',
 							supported:   'not',
 							description: '_Handle S3 classes and methods as one unit (with attributes etc.). Including Dispatch and Inheritance._ We do not support typing currently and do not handle objects of these classes "as units."'
 						},
 						{
 							name:        'S4',
 							id:          'oop-s4',
-							note:        'https://adv-r.hadley.nz/s4.html',
+							example:     'https://adv-r.hadley.nz/s4.html',
 							supported:   'not',
 							description: '_Handle S4 classes and methods as one unit. Including Dispatch and Inheritance_ We do not support typing currently and do not handle objects of these classes "as units."'
 						},
 						{
 							name:        'R6',
 							id:          'oop-r6',
-							note:        'https://adv-r.hadley.nz/r6.html',
+							example:     'https://adv-r.hadley.nz/r6.html',
 							supported:   'not',
 							description: '_Handle R6 classes and methods as one unit. Including Dispatch and Inheritance, as well as its Reference Semantics, Access Control, Finalizers, and Introspection._ We do not support typing currently and do not handle objects of these classes "as units."'
 						},
 						{
 							name:        'R7/S7',
 							id:          'r7-s7',
-							note:        'https://www.r-bloggers.com/2022/12/what-is-r7-a-new-oop-system-for-r/, https://cran.r-project.org/web/packages/S7/index.html',
+							example:     'https://www.r-bloggers.com/2022/12/what-is-r7-a-new-oop-system-for-r/, https://cran.r-project.org/web/packages/S7/index.html',
 							supported:   'not',
 							description: '_Handle R7 classes and methods as one unit. Including Dispatch and Inheritance, as well as its Reference Semantics, Validators, ..._ We do not support typing currently and do not handle objects of these classes "as units."'
 						}

src/r-bridge/data/types.ts

@@ -1,3 +1,5 @@
+import type { KnownParser } from '../parser';
+
 const enum RequiredFeature {
 	/** https://github.com/flowr-analysis/flowr/labels/typing */
 	Typing,
@@ -16,7 +18,10 @@ export interface FlowrCapability {
 	/** A list of features that are required for the capability, extend at need. */
 	readonly needs?:        RequiredFeature[]
 	readonly description?:  string
-	readonly note?:         string
+	/* examples may be generated on demand */
+	readonly example?:      string | ((parser: KnownParser) => Promise<string>),
+	/** A list of URLs that provide additional information about the capability */
+	readonly url?:          { name: string, href: string }[]
 	/** The level of support for the capability, undefined if it is a meta-capability that does not need such an attribute */
 	readonly supported?:    'not' | 'partially' | 'fully'
 	readonly capabilities?: readonly FlowrCapability[]