Context Sensitive Call Pattern Queries (#1009)

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

@@ -75,7 +75,8 @@ jobs:
           }
           
           update_wiki_page "Capabilities" capabilities-markdown
-          update_wiki_page "Dataflow Graph" df-graph-wiki-markdown 
+          update_wiki_page "Dataflow Graph" wiki:df-graph
+          update_wiki_page "Query API" wiki:query-api
           
           if [ $CHANGED_ANY == "true" ]; then
               git config --local user.email "action@github.com"

package.json

@@ -25,7 +25,8 @@
     "summarizer": "ts-node src/cli/summarizer-app.ts",
     "export-quads": "ts-node src/cli/export-quads-app.ts",
     "capabilities-markdown": "ts-node src/documentation/print-capabilities-markdown.ts",
-    "df-graph-wiki-markdown": "ts-node src/documentation/print-dataflow-graph-wiki.ts",
+    "wiki:df-graph": "ts-node src/documentation/print-dataflow-graph-wiki.ts",
+    "wiki:query-api": "ts-node src/documentation/print-query-wiki.ts",
     "build": "tsc --project .",
     "build:bundle-flowr": "npm run build && esbuild --bundle dist/src/cli/flowr.js --platform=node --bundle --minify --target=node18 --outfile=dist/src/cli/flowr.min.js",
     "lint-local": "npx eslint --version && npx eslint src/ test/ --rule \"no-warning-comments: off\"",

src/cli/common/scripts-info.ts

@@ -12,7 +12,7 @@ import {
 	summarizerOptions
 } from './options';
 import type { MergeableRecord } from '../../util/objects';
-import { asOptionName } from '../repl/commands/commands';
+import { asOptionName } from '../repl/commands/repl-commands';
 
 
 interface BaseScriptInformation extends MergeableRecord {

src/cli/flowr.ts

@@ -23,9 +23,9 @@ import { scripts } from './common/scripts-info';
 import type { RShellOptions } from '../r-bridge/shell';
 import { RShell, RShellReviveOptions } from '../r-bridge/shell';
 import { waitOnScript } from './repl/execute';
-import { standardReplOutput } from './repl/commands/main';
+import { standardReplOutput } from './repl/commands/repl-main';
 import { repl, replProcessAnswer } from './repl/core';
-import { printVersionInformation } from './repl/commands/version';
+import { printVersionInformation } from './repl/commands/repl-version';
 import { printVersionRepl } from './repl/print-version';
 
 let _scriptsText: string | undefined;

src/cli/repl/commands/cfg.ts → src/cli/repl/commands/repl-cfg.ts

@@ -1,4 +1,4 @@
-import type { ReplCommand } from './main';
+import type { ReplCommand } from './repl-main';
 import { PipelineExecutor } from '../../../core/pipeline-executor';
 import { extractCFG } from '../../../util/cfg/cfg';
 import type { RShell } from '../../../r-bridge/shell';
@@ -27,8 +27,8 @@ export const controlflowCommand: ReplCommand = {
 };
 
 export const controlflowStarCommand: ReplCommand = {
-	description:  `Get a mermaid url of the control-flow graph of R code, start with '${fileProtocol}' to indicate a file`,
-	usageExample: ':controlflow',
+	description:  'Returns the URL to mermaid.live',
+	usageExample: ':controlflow*',
 	aliases:      [ 'cfg*', 'cf*' ],
 	script:       false,
 	fn:           async(output, shell, remainingLine) => {

src/cli/repl/commands/commands.ts → src/cli/repl/commands/repl-commands.ts

@@ -1,29 +1,48 @@
-import { quitCommand } from './quit';
+import { quitCommand } from './repl-quit';
 import { stdioCaptureProcessor, waitOnScript } from '../execute';
-import type { ReplCommand } from './main';
+import type { ReplCommand } from './repl-main';
 import { rawPrompt } from '../prompt';
-import { versionCommand } from './version';
-import { parseCommand } from './parse';
-import { executeCommand } from './execute';
-import { normalizeCommand, normalizeStarCommand } from './normalize';
-import { dataflowCommand, dataflowStarCommand } from './dataflow';
-import { controlflowCommand, controlflowStarCommand } from './cfg';
+import { versionCommand } from './repl-version';
+import { parseCommand } from './repl-parse';
+import { executeCommand } from './repl-execute';
+import { normalizeCommand, normalizeStarCommand } from './repl-normalize';
+import { dataflowCommand, dataflowStarCommand } from './repl-dataflow';
+import { controlflowCommand, controlflowStarCommand } from './repl-cfg';
 import type { OutputFormatter } from '../../../util/ansi';
 import { italic , bold } from '../../../util/ansi';
 import { splitAtEscapeSensitive } from '../../../util/args';
 import { guard } from '../../../util/assert';
 import { scripts } from '../../common/scripts-info';
-import { getLineageCommand } from './lineage';
+import { lineageCommand } from './repl-lineage';
+import { queryCommand, queryStarCommand } from './repl-query';
 
-function printHelpForScript(script: [string, ReplCommand], f: OutputFormatter): string {
-	const base = `  ${bold(padCmd(':' + script[0]), f)}${script[1].description}`;
+function printHelpForScript(script: [string, ReplCommand], f: OutputFormatter, starredVersion?: ReplCommand): string {
+	let base = `  ${bold(padCmd(':' + script[0] + (starredVersion ? '[*]' : '') 
+	), f)}${script[1].description}`;
+	if(starredVersion) {
+		base += ` (star: ${starredVersion.description})`;
+	}
 	if(script[1].aliases.length === 0) {
 		return base;
 	}
 	const aliases = script[1].aliases;
 	return `${base} (alias${aliases.length > 1 ? 'es' : ''}: ${aliases.map(a => bold(':' + a, f)).join(', ')})`;
 }
 
+function printCommandHelp(formatter: OutputFormatter) {
+	const scriptHelp = [];
+	const cmds = commands();
+	for(const c of Object.entries(cmds)) {
+		if(c[1].script || c[0].endsWith('*')) {
+			continue;
+		}
+		const starred =  cmds[c[0] + '*'];
+		scriptHelp.push(printHelpForScript(c, formatter, starred));
+	}
+
+	return scriptHelp.sort().join('\n');
+}
+
 export const helpCommand: ReplCommand = {
 	description:  'Show help information',
 	script:       false,
@@ -32,20 +51,20 @@ export const helpCommand: ReplCommand = {
 	fn:           output => {
 		initCommandMapping();
 		output.stdout(`
-If enabled, you can just enter R expressions which get evaluated right away:
+If enabled ('--r-session-access'), you can just enter R expressions which get evaluated right away:
 ${rawPrompt} ${bold('1 + 1', output.formatter)}
 ${italic('[1] 2', output.formatter)}
 
-Besides that, you can use the following commands. The scripts ${italic('can', output.formatter)} accept further arguments. There are the following basic commands:
+Besides that, you can use the following commands. The scripts ${italic('can', output.formatter)} accept further arguments. In general, those ending with [*] may be called with and without the star. 
+There are the following basic commands:
 ${
-	Array.from(Object.entries(commands())).filter(([, { script }]) => !script).map(
-		c => printHelpForScript(c, output.formatter)).join('\n')
+	printCommandHelp(output.formatter)
 }
 
 Furthermore, you can directly call the following scripts which accept arguments. If you are unsure, try to add ${italic('--help', output.formatter)} after the command.
 ${
 	Array.from(Object.entries(commands())).filter(([, { script }]) => script).map(
-		([command, { description }]) => `  ${bold(padCmd(':' + command), output.formatter)}${description}`).join('\n')
+		([command, { description }]) => `  ${bold(padCmd(':' + command), output.formatter)}${description}`).sort().join('\n')
 }
 
 You can combine commands by separating them with a semicolon ${bold(';',output.formatter)}.
@@ -68,7 +87,9 @@ const _commands: Record<string, ReplCommand> = {
 	'dataflow*':    dataflowStarCommand,
 	'controlflow':  controlflowCommand,
 	'controlflow*': controlflowStarCommand,
-	'lineage':      getLineageCommand
+	'lineage':      lineageCommand,
+	'query':        queryCommand,
+	'query*':       queryStarCommand
 };
 let commandsInitialized = false;
 
@@ -167,7 +188,7 @@ export function asOptionName(argument: string): string{
 let _longestCommandName: number | undefined = undefined;
 export function longestCommandName(): number {
 	if(_longestCommandName === undefined) {
-		_longestCommandName = Array.from(Object.keys(commands()), k => k.length).reduce((p, n) => Math.max(p, n), 0);
+		_longestCommandName = Array.from(Object.keys(commands()), k => k.endsWith('*') ? k.length + 3 : k.length).reduce((p, n) => Math.max(p, n), 0);
 	}
 	return _longestCommandName;
 }

src/cli/repl/commands/dataflow.ts → src/cli/repl/commands/repl-dataflow.ts

@@ -1,4 +1,4 @@
-import type { ReplCommand } from './main';
+import type { ReplCommand } from './repl-main';
 import { PipelineExecutor } from '../../../core/pipeline-executor';
 import { DEFAULT_DATAFLOW_PIPELINE } from '../../../core/steps/pipeline/default-pipelines';
 import type { RShell } from '../../../r-bridge/shell';
@@ -25,7 +25,7 @@ export const dataflowCommand: ReplCommand = {
 };
 
 export const dataflowStarCommand: ReplCommand = {
-	description:  `Get a mermaid url of the dataflow graph of R code, start with '${fileProtocol}' to indicate a file`,
+	description:  'Returns the URL to mermaid.live',
 	usageExample: ':dataflow*',
 	aliases:      [ 'd*', 'df*' ],
 	script:       false,

src/cli/repl/commands/execute.ts → src/cli/repl/commands/repl-execute.ts

@@ -1,4 +1,4 @@
-import type { ReplCommand, ReplOutput } from './main';
+import type { ReplCommand, ReplOutput } from './repl-main';
 import { italic } from '../../../util/ansi';
 import type { RShell } from '../../../r-bridge/shell';
 

src/cli/repl/commands/lineage.ts → src/cli/repl/commands/repl-lineage.ts

@@ -1,4 +1,4 @@
-import type { ReplCommand } from './main';
+import type { ReplCommand } from './repl-main';
 import { PipelineExecutor } from '../../../core/pipeline-executor';
 import { DEFAULT_DATAFLOW_PIPELINE } from '../../../core/steps/pipeline/default-pipelines';
 import type { RShell } from '../../../r-bridge/shell';
@@ -65,7 +65,7 @@ export function getLineage(criterion: SingleSlicingCriterion, { idMap } : Normal
 	return result;
 }
 
-export const getLineageCommand: ReplCommand = {
+export const lineageCommand: ReplCommand = {
 	description:  'Get the lineage of an R object',
 	usageExample: ':lineage',
 	aliases:      ['lin'],

src/cli/repl/commands/normalize.ts → src/cli/repl/commands/repl-normalize.ts

@@ -1,4 +1,4 @@
-import type { ReplCommand } from './main';
+import type { ReplCommand } from './repl-main';
 import { PipelineExecutor } from '../../../core/pipeline-executor';
 import { DEFAULT_NORMALIZE_PIPELINE } from '../../../core/steps/pipeline/default-pipelines';
 import type { RShell } from '../../../r-bridge/shell';
@@ -25,8 +25,8 @@ export const normalizeCommand: ReplCommand = {
 };
 
 export const normalizeStarCommand: ReplCommand = {
-	description:  `Get a mermaid url of the normalized AST of R code, start with '${fileProtocol}' to indicate a file`,
-	usageExample: ':normalize',
+	description:  'Returns the URL to mermaid.live',
+	usageExample: ':normalize*',
 	aliases:      [ 'n*' ],
 	script:       false,
 	fn:           async(output, shell, remainingLine) => {

src/cli/repl/commands/parse.ts → src/cli/repl/commands/repl-parse.ts

@@ -1,4 +1,4 @@
-import type { ReplCommand } from './main';
+import type { ReplCommand } from './repl-main';
 import type { OutputFormatter } from '../../../util/ansi';
 import { FontStyles } from '../../../util/ansi';
 import { PipelineExecutor } from '../../../core/pipeline-executor';
@@ -19,7 +19,7 @@ type DepthList =  { depth: number, node: XmlBasedJson, leaf: boolean }[]
 
 function toDepthMap(xml: XmlBasedJson): DepthList {
 	const root = getKeyGuarded<XmlBasedJson>(xml, RawRType.ExpressionList);
-	
+
 	const visit: { depth: number, node: XmlBasedJson }[] = [ { depth: 0, node: root } ];
 	const result: DepthList = [];
 
@@ -30,7 +30,7 @@ function toDepthMap(xml: XmlBasedJson): DepthList {
 		}
 
 		const children = current.node[childrenKey] as unknown as XmlBasedJson[] | undefined ?? [];
-		
+
 		result.push({ ...current, leaf: children.length === 0 });
 		children.reverse();