Add location based restrictions to call context query (#1166)

* feat: first shot at file filtering for call-context queries

* feat: includeUndefinedFiles defaults to true

* feat-doc: added comments

* feat: fixed issues with file filter in call context queries

* doc-fix: added missing newline

* doc: added doc for file filters in call context queries

src/documentation/print-query-wiki.ts

@@ -54,6 +54,13 @@ Besides this, we provide the following ways to automatically categorize and link
    For now, we _only_ offer support for linking to the last call, as the current flow dependency over-approximation is not stable.
 4. **Aliases**      (\`includeAliases\`): Consider a case like \`f <- function_of_interest\`, do you want calls to \`f\` to be included in the results? There is probably no need to combine this with a global call target!
 
+It's also possible to filter the results based on the following properties:
+
+1. **File** (\`fileFilter\`): This allows you to filter the results based on the file in which the call is located. This can be useful if you are only interested in calls in, e.g., specific folders.
+  The \`fileFilter\` property is an object made up of two properties:
+  - **Filter** (\`filter\`): A regular expression that a node's file attribute must match to be considered.
+  - **Include Undefined Files** (\`includeUndefinedFiles\`): If \`fileFilter\` is set, but a node's file attribute is not present, should we include it in the results? Defaults to \`true\`.
+
 Re-using the example code from above, the following query attaches all calls to \`mean\` to the kind \`visualize\` and the subkind \`text\`,
 all calls that start with \`read_\` to the kind \`input\` but only if they are not locally overwritten, and the subkind \`csv-file\`, and links all calls to \`points\` to the last call to \`plot\`:
 
@@ -98,6 +105,7 @@ my_test_function()
 		`;
 	}
 });
+
 registerQueryDocumentation('dataflow', {
 	name:             'Dataflow Query',
 	type:             'active',

src/queries/catalog/call-context-query/call-context-query-executor.ts

@@ -4,6 +4,7 @@ import type {
 	CallContextQueryKindResult,
 	CallContextQueryResult,
 	CallContextQuerySubKindResult,
+	FileFilter,
 	SubCallContextQueryFormat
 } from './call-context-query-format';
 import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
@@ -64,6 +65,10 @@ function promoteQueryCallNames(queries: readonly CallContextQuery[]): { promoted
 				...q,
 				callName: q.callNameExact ? exactCallNameRegex(q.callName)
 					: new RegExp(q.callName),
+				fileFilter: q.fileFilter && {
+					...q.fileFilter,
+					filter: new RegExp(q.fileFilter.filter)
+				},
 				linkTo: {
 					...q.linkTo,
 					/* we have to add another promotion layer whenever we add something without this call name */
@@ -74,7 +79,11 @@ function promoteQueryCallNames(queries: readonly CallContextQuery[]): { promoted
 			return {
 				...q,
 				callName: q.callNameExact ? exactCallNameRegex(q.callName)
-					: new RegExp(q.callName)
+					: new RegExp(q.callName),
+				fileFilter: q.fileFilter && {
+					...q.fileFilter,
+					filter: new RegExp(q.fileFilter.filter)
+				}
 			};
 		}
 	});
@@ -156,6 +165,16 @@ function removeIdenticalDuplicates(collector: TwoLayerCollector<string, string,
 	}
 }
 
+function doesFilepathMatch(file: string | undefined, filter: FileFilter<RegExp> | undefined): boolean {
+	if(filter === undefined) {
+		return true;
+	}
+	if(file === undefined) {
+		return filter.includeUndefinedFiles ?? true;
+	}
+	return filter.filter.test(file);
+}
+
 /**
  * Multi-stage call context query resolve.
  *
@@ -203,6 +222,11 @@ export function executeCallContextQueries({ graph, ast }: BasicQueryData, querie
 		}
 
 		for(const query of promotedQueries.filter(q => q.callName.test(info.name))) {
+			const file = ast.idMap.get(nodeId)?.info.file;
+			if(!doesFilepathMatch(file, query.fileFilter)) {
+				continue;
+			}
+
 			let targets: NodeId[] | 'no' | undefined = undefined;
 			if(query.callTargets) {
 				targets = satisfiesCallTargets(nodeId, graph, query.callTargets);

src/queries/catalog/call-context-query/call-context-query-format.ts

@@ -11,10 +11,21 @@ import type { PipelineOutput } from '../../../core/steps/pipeline/pipeline';
 import type { DEFAULT_DATAFLOW_PIPELINE } from '../../../core/steps/pipeline/default-pipelines';
 import { CallTargets } from './identify-link-to-last-call-relation';
 
-export interface DefaultCallContextQueryFormat<CallName extends RegExp | string> extends BaseQueryFormat {
+export interface FileFilter<FilterType> {
+	/**
+	 * Regex that a node's file attribute must match to be considered
+	 */
+	readonly filter:                 FilterType;
+	/**
+	 * If `fileFilter` is set, but a nodes `file` attribute is `undefined`, should we include it in the results? Defaults to `true`.
+	 */
+	readonly includeUndefinedFiles?: boolean;
+}
+
+export interface DefaultCallContextQueryFormat<RegexType extends RegExp | string> extends BaseQueryFormat {
 	readonly type:            'call-context';
 	/** Regex regarding the function name, please note that strings will be interpreted as regular expressions too! */
-	readonly callName:        CallName;
+	readonly callName:        RegexType;
 	/**
 	 * Should we automatically add the `^` and `$` anchors to the regex to make it an exact match?
 	 */
@@ -32,6 +43,10 @@ export interface DefaultCallContextQueryFormat<CallName extends RegExp | string>
 	 * Consider a case like `f <- function_of_interest`, do you want uses of `f` to be included in the results?
 	 */
 	readonly includeAliases?: boolean;
+	/**
+	 * Filter that, when set, a node's file attribute must match to be considered
+	 */
+	readonly fileFilter?:     FileFilter<RegexType>;
 }
 
 /**
@@ -98,7 +113,11 @@ export const CallContextQueryDefinition = {
 		subkind:        Joi.string().optional().description('The subkind of the call, this can be used to uniquely identify the respective call type when grouping the output (e.g., the normalized name, linking `ggplot` to `plot`). Defaults to `.`'),
 		callTargets:    Joi.string().valid(...Object.values(CallTargets)).optional().description('Call targets the function may have. This defaults to `any`. Request this specifically to gain all call targets we can resolve.'),
 		includeAliases: Joi.boolean().optional().description('Consider a case like `f <- function_of_interest`, do you want uses of `f` to be included in the results?'),
-		linkTo:         Joi.object({
+		fileFilter:     Joi.object({
+			fileFilter:            Joi.string().required().description('Regex that a node\'s file attribute must match to be considered'),
+			includeUndefinedFiles: Joi.boolean().optional().description('If `fileFilter` is set, but a nodes `file` attribute is `undefined`, should we include it in the results? Defaults to `true`.')
+		}).optional().description('Filter that, when set, a node\'s file attribute must match to be considered'),
+		linkTo: Joi.object({
 			type:     Joi.string().valid('link-to-last-call').required().description('The type of the linkTo sub-query.'),
 			callName: Joi.string().required().description('Regex regarding the function name of the last call. Similar to `callName`, strings are interpreted as a regular expression.')
 		}).optional().description('Links the current call to the last call of the given kind. This way, you can link a call like `points` to the latest graphics plot etc.')