@eagleoutice/flowr 2.1.7 → 2.1.8

package/README.md

@@ -34,7 +34,6 @@ We welcome every contribution! Please check out the [contributing guidelines](ht
 ### Contributors
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!--suppress ALL -->
 <!-- prettier-ignore-start -->
 <!-- markdownlint-disable -->
 <table>
@@ -42,6 +41,7 @@ We welcome every contribution! Please check out the [contributing guidelines](ht
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/EagleoutIce"><img src="https://avatars.githubusercontent.com/u/9303573?v=4?s=100" width="100px;" alt="Florian Sihler"/><br /><sub><b>Florian Sihler</b></sub></a><br /><a href="https://github.com/flowr-analysis/flowr/commits?author=EagleoutIce" title="Code">💻</a> <a href="#ideas-EagleoutIce" title="Ideas, Planning, & Feedback">🤔</a> <a href="#maintenance-EagleoutIce" title="Maintenance">🚧</a> <a href="#projectManagement-EagleoutIce" title="Project Management">📆</a> <a href="#research-EagleoutIce" title="Research">🔬</a> <a href="https://github.com/flowr-analysis/flowr/commits?author=EagleoutIce" title="Tests">⚠️</a> <a href="#talk-EagleoutIce" title="Talks">📢</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://ellpeck.de/"><img src="https://avatars.githubusercontent.com/u/5741138?v=4?s=100" width="100px;" alt="Ell"/><br /><sub><b>Ell</b></sub></a><br /><a href="https://github.com/flowr-analysis/flowr/commits?author=Ellpeck" title="Code">💻</a> <a href="#maintenance-Ellpeck" title="Maintenance">🚧</a> <a href="https://github.com/flowr-analysis/flowr/commits?author=Ellpeck" title="Tests">⚠️</a> <a href="#plugin-Ellpeck" title="Plugin/utility libraries">🔌</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/gigalasr"><img src="https://avatars.githubusercontent.com/u/25102989?v=4?s=100" width="100px;" alt="Lars"/><br /><sub><b>Lars</b></sub></a><br /><a href="https://github.com/flowr-analysis/flowr/commits?author=gigalasr" title="Code">💻</a> <a href="https://github.com/flowr-analysis/flowr/commits?author=gigalasr" title="Tests">⚠️</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://lukas.pietzschmann.org/"><img src="https://avatars.githubusercontent.com/u/49213919?v=4?s=100" width="100px;" alt="Lukas Pietzschmann"/><br /><sub><b>Lukas Pietzschmann</b></sub></a><br /><a href="https://github.com/flowr-analysis/flowr/commits?author=LukasPietzschmann" title="Code">💻</a> <a href="https://github.com/flowr-analysis/flowr/commits?author=LukasPietzschmann" title="Tests">⚠️</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/bjthehun"><img src="https://avatars.githubusercontent.com/u/38729215?v=4?s=100" width="100px;" alt="Benedikt Jutz"/><br /><sub><b>Benedikt Jutz</b></sub></a><br /><a href="https://github.com/flowr-analysis/flowr/commits?author=bjthehun" title="Code">💻</a> <a href="https://github.com/flowr-analysis/flowr/commits?author=bjthehun" title="Tests">⚠️</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Core5563"><img src="https://avatars.githubusercontent.com/u/140061253?v=4?s=100" width="100px;" alt="Core5563"/><br /><sub><b>Core5563</b></sub></a><br /><a href="https://github.com/flowr-analysis/flowr/commits?author=Core5563" title="Code">💻</a> <a href="https://github.com/flowr-analysis/flowr/commits?author=Core5563" title="Tests">⚠️</a></td>
@@ -61,6 +61,7 @@ We welcome every contribution! Please check out the [contributing guidelines](ht
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 ----

package/abstract-interpretation/normalized-ast-fold.d.ts

@@ -0,0 +1,124 @@
+import type { NoInfo, RNode } from '../r-bridge/lang-4.x/ast/model/model';
+import type { RExpressionList } from '../r-bridge/lang-4.x/ast/model/nodes/r-expression-list';
+import type { RFunctionCall } from '../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
+import { EmptyArgument } from '../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
+import type { RFunctionDefinition } from '../r-bridge/lang-4.x/ast/model/nodes/r-function-definition';
+import { RType } from '../r-bridge/lang-4.x/ast/model/type';
+import type { RForLoop } from '../r-bridge/lang-4.x/ast/model/nodes/r-for-loop';
+import type { RWhileLoop } from '../r-bridge/lang-4.x/ast/model/nodes/r-while-loop';
+import type { RRepeatLoop } from '../r-bridge/lang-4.x/ast/model/nodes/r-repeat-loop';
+import type { RIfThenElse } from '../r-bridge/lang-4.x/ast/model/nodes/r-if-then-else';
+import type { RBinaryOp } from '../r-bridge/lang-4.x/ast/model/nodes/r-binary-op';
+import type { RPipe } from '../r-bridge/lang-4.x/ast/model/nodes/r-pipe';
+import type { RUnaryOp } from '../r-bridge/lang-4.x/ast/model/nodes/r-unary-op';
+import type { RParameter } from '../r-bridge/lang-4.x/ast/model/nodes/r-parameter';
+import type { RArgument } from '../r-bridge/lang-4.x/ast/model/nodes/r-argument';
+import type { RAccess } from '../r-bridge/lang-4.x/ast/model/nodes/r-access';
+import type { RLogical } from '../r-bridge/lang-4.x/ast/model/nodes/r-logical';
+import type { RBreak } from '../r-bridge/lang-4.x/ast/model/nodes/r-break';
+import type { RComment } from '../r-bridge/lang-4.x/ast/model/nodes/r-comment';
+import type { RNext } from '../r-bridge/lang-4.x/ast/model/nodes/r-next';
+import type { RNumber } from '../r-bridge/lang-4.x/ast/model/nodes/r-number';
+import type { RLineDirective } from '../r-bridge/lang-4.x/ast/model/nodes/r-line-directive';
+import type { RString } from '../r-bridge/lang-4.x/ast/model/nodes/r-string';
+import type { RSymbol } from '../r-bridge/lang-4.x/ast/model/nodes/r-symbol';
+type FoldOfType<T extends RType, Returns = void, Info = NoInfo> = (node: Extract<RNode<Info>, {
+    type: T;
+}>) => Returns;
+/** explicitly excludes types that are not visitable */
+export type FoldableRType = Exclude<RType, RType.Delimiter>;
+/**
+ * Describes the fold functions for each node type.
+ */
+export type NormalizedAstFold<Returns = void, Info = NoInfo> = {
+    [K in FoldableRType as `fold${Capitalize<K>}`]: FoldOfType<K, Returns, Info>;
+};
+/**
+ * Describes the type of a mapping object,
+ * which maps the type of the normalized AST node to the corresponding fold function.
+ */
+export type FittingNormalizedAstFold<Returns = void, Info = NoInfo> = Readonly<{
+    [K in FoldableRType]: FoldOfType<K, Returns, Info>;
+}>;
+export type SingleOrArrayOrNothing<T> = T | readonly (T | null | undefined)[] | null | undefined;
+export type EntryExitVisitor<Info> = ((node: RNode<Info>) => void) | undefined;
+/**
+ * Default implementation of a fold over the normalized AST (using the classic fold traversal).
+ * To modify the behavior, please extend this class and overwrite the methods of interest.
+ * You can control the value passing (`Returns` generic)
+ * by providing sensible Monoid behavior overwriting the {@link DefaultNormalizedAstFold#concat|concat} method
+ * and supplying the empty value in the constructor.
+ *
+ * @note By providing `entry` and `exit` you can use this as an extension to the simpler {@link visitAst} function but without
+ *       the early termination within the visitors (for this, you can overwrite the respective `fold*` methods).
+ *
+ * @example First you want to create your own fold:
+ *
+ * ```ts
+ * let marker = false;
+ * class MyNumberFold<Info> extends DefaultNormalizedAstFold<void, Info> {
+ *     override foldRNumber(node: RNumber<Info>) {
+ *         super.foldRNumber(node);
+ *         marker = true;
+ *     }
+ * }
+ * ```
+ * This one does explicitly not use the return functionality (and hence acts more as a conventional visitor).
+ * Now let us suppose we have a normalized AST as an {@link RNode} in the variable `ast`
+ * and want to check if the AST contains a number:
+ *
+ * ```ts
+ * const result = new MyNumberFold().fold(ast);
+ * ```
+ *
+ * Please take a look at the corresponding tests or the wiki pages for more information on how to use this fold.
+ */
+export declare class DefaultNormalizedAstFold<Returns = void, Info = NoInfo> implements NormalizedAstFold<Returns, Info> {
+    protected readonly enter: EntryExitVisitor<Info>;
+    protected readonly exit: EntryExitVisitor<Info>;
+    protected readonly empty: Returns;
+    /**
+     * Empty must provide a sensible default whenever you want to have `Returns` as non-`void`
+     * (e.g., whenever you want your visitors to be able to return a value).
+     */
+    constructor(empty: Returns, enter?: EntryExitVisitor<Info>, exit?: EntryExitVisitor<Info>);
+    /**
+     * Monoid::concat
+     *
+     *
+     * @see {@link https://en.wikipedia.org/wiki/Monoid}
+     * @see {@link DefaultNormalizedAstFold#concatAll|concatAll}
+     */
+    protected concat(_a: Returns, _b: Returns): Returns;
+    /**
+     * overwrite this method, if you have a faster way to concat multiple nodes
+     *
+     * @see {@link DefaultNormalizedAstFold#concatAll|concatAll}
+     */
+    protected concatAll(nodes: readonly Returns[]): Returns;
+    fold(nodes: SingleOrArrayOrNothing<RNode<Info> | typeof EmptyArgument>): Returns;
+    protected foldSingle(node: RNode<Info>): Returns;
+    foldRAccess(access: RAccess<Info>): Returns;
+    foldRArgument(argument: RArgument<Info>): Returns;
+    foldRBinaryOp(binaryOp: RBinaryOp<Info>): Returns;
+    foldRExpressionList(exprList: RExpressionList<Info>): Returns;
+    foldRForLoop(loop: RForLoop<Info>): Returns;
+    foldRFunctionCall(call: RFunctionCall<Info>): Returns;
+    foldRFunctionDefinition(definition: RFunctionDefinition<Info>): Returns;
+    foldRIfThenElse(ite: RIfThenElse<Info>): Returns;
+    foldRParameter(parameter: RParameter<Info>): Returns;
+    foldRPipe(pipe: RPipe<Info>): Returns;
+    foldRRepeatLoop(loop: RRepeatLoop<Info>): Returns;
+    foldRUnaryOp(unaryOp: RUnaryOp<Info>): Returns;
+    foldRWhileLoop(loop: RWhileLoop<Info>): Returns;
+    foldRBreak(_node: RBreak<Info>): Returns;
+    foldRComment(_node: RComment<Info>): Returns;
+    foldRLineDirective(_node: RLineDirective<Info>): Returns;
+    foldRLogical(_node: RLogical<Info>): Returns;
+    foldRNext(_node: RNext<Info>): Returns;
+    foldRNumber(_node: RNumber<Info>): Returns;
+    foldRString(_node: RString<Info>): Returns;
+    foldRSymbol(_node: RSymbol<Info>): Returns;
+    protected readonly folds: FittingNormalizedAstFold<Returns, Info>;
+}
+export {};

package/abstract-interpretation/normalized-ast-fold.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultNormalizedAstFold = void 0;
+const r_function_call_1 = require("../r-bridge/lang-4.x/ast/model/nodes/r-function-call");
+const type_1 = require("../r-bridge/lang-4.x/ast/model/type");
+/**
+ * Default implementation of a fold over the normalized AST (using the classic fold traversal).
+ * To modify the behavior, please extend this class and overwrite the methods of interest.
+ * You can control the value passing (`Returns` generic)
+ * by providing sensible Monoid behavior overwriting the {@link DefaultNormalizedAstFold#concat|concat} method
+ * and supplying the empty value in the constructor.
+ *
+ * @note By providing `entry` and `exit` you can use this as an extension to the simpler {@link visitAst} function but without
+ *       the early termination within the visitors (for this, you can overwrite the respective `fold*` methods).
+ *
+ * @example First you want to create your own fold:
+ *
+ * ```ts
+ * let marker = false;
+ * class MyNumberFold<Info> extends DefaultNormalizedAstFold<void, Info> {
+ *     override foldRNumber(node: RNumber<Info>) {
+ *         super.foldRNumber(node);
+ *         marker = true;
+ *     }
+ * }
+ * ```
+ * This one does explicitly not use the return functionality (and hence acts more as a conventional visitor).
+ * Now let us suppose we have a normalized AST as an {@link RNode} in the variable `ast`
+ * and want to check if the AST contains a number:
+ *
+ * ```ts
+ * const result = new MyNumberFold().fold(ast);
+ * ```
+ *
+ * Please take a look at the corresponding tests or the wiki pages for more information on how to use this fold.
+ */
+class DefaultNormalizedAstFold {
+    enter;
+    exit;
+    empty;
+    /**
+     * Empty must provide a sensible default whenever you want to have `Returns` as non-`void`
+     * (e.g., whenever you want your visitors to be able to return a value).
+     */
+    constructor(empty, enter, exit) {
+        this.empty = empty;
+        this.enter = enter;
+        this.exit = exit;
+    }
+    /**
+     * Monoid::concat
+     *
+     *
+     * @see {@link https://en.wikipedia.org/wiki/Monoid}
+     * @see {@link DefaultNormalizedAstFold#concatAll|concatAll}
+     */
+    concat(_a, _b) {
+        return this.empty;
+    }
+    /**
+     * overwrite this method, if you have a faster way to concat multiple nodes
+     *
+     * @see {@link DefaultNormalizedAstFold#concatAll|concatAll}
+     */
+    concatAll(nodes) {
+        return nodes.reduce((acc, n) => this.concat(acc, n), this.empty);
+    }
+    fold(nodes) {
+        if (Array.isArray(nodes)) {
+            const n = nodes;
+            return this.concatAll(n.filter(n => n && n !== r_function_call_1.EmptyArgument).map(node => this.foldSingle(node)));
+        }
+        else if (nodes) {
+            return this.foldSingle(nodes);
+        }
+        return this.empty;
+    }
+    foldSingle(node) {
+        this.enter?.(node);
+        const type = node.type;
+        // @ts-expect-error -- ts may be unable to infer that the type is correct
+        const result = this.folds[type]?.(node);
+        this.exit?.(node);
+        return result;
+    }
+    foldRAccess(access) {
+        let accessed = this.foldSingle(access.accessed);
+        if (access.operator === '[' || access.operator === '[[') {
+            accessed = this.concat(accessed, this.fold(access.access));
+        }
+        return accessed;
+    }
+    foldRArgument(argument) {
+        return this.concat(this.fold(argument.name), this.fold(argument.value));
+    }
+    foldRBinaryOp(binaryOp) {
+        return this.concat(this.foldSingle(binaryOp.lhs), this.foldSingle(binaryOp.rhs));
+    }
+    foldRExpressionList(exprList) {
+        return this.concat(this.fold(exprList.grouping), this.fold(exprList.children));
+    }
+    foldRForLoop(loop) {
+        return this.concatAll([this.foldSingle(loop.variable), this.foldSingle(loop.vector), this.foldSingle(loop.body)]);
+    }
+    foldRFunctionCall(call) {
+        return this.concat(this.foldSingle(call.named ? call.functionName : call.calledFunction), this.fold(call.arguments));
+    }
+    foldRFunctionDefinition(definition) {
+        return this.concat(this.fold(definition.parameters), this.foldSingle(definition.body));
+    }
+    foldRIfThenElse(ite) {
+        return this.concatAll([this.foldSingle(ite.condition), this.foldSingle(ite.then), this.fold(ite.otherwise)]);
+    }
+    foldRParameter(parameter) {
+        return this.concat(this.foldSingle(parameter.name), this.fold(parameter.defaultValue));
+    }
+    foldRPipe(pipe) {
+        return this.concat(this.foldSingle(pipe.lhs), this.foldSingle(pipe.rhs));
+    }
+    foldRRepeatLoop(loop) {
+        return this.foldSingle(loop.body);
+    }
+    foldRUnaryOp(unaryOp) {
+        return this.foldSingle(unaryOp.operand);
+    }
+    foldRWhileLoop(loop) {
+        return this.concat(this.foldSingle(loop.condition), this.foldSingle(loop.body));
+    }
+    foldRBreak(_node) {
+        return this.empty;
+    }
+    foldRComment(_node) {
+        return this.empty;
+    }
+    foldRLineDirective(_node) {
+        return this.empty;
+    }
+    foldRLogical(_node) {
+        return this.empty;
+    }
+    foldRNext(_node) {
+        return this.empty;
+    }
+    foldRNumber(_node) {
+        return this.empty;
+    }
+    foldRString(_node) {
+        return this.empty;
+    }
+    foldRSymbol(_node) {
+        return this.empty;
+    }
+    folds = {
+        [type_1.RType.Access]: n => this.foldRAccess(n),
+        [type_1.RType.Argument]: n => this.foldRArgument(n),
+        [type_1.RType.BinaryOp]: n => this.foldRBinaryOp(n),
+        [type_1.RType.Break]: n => this.foldRBreak(n),
+        [type_1.RType.Comment]: n => this.foldRComment(n),
+        [type_1.RType.ExpressionList]: n => this.foldRExpressionList(n),
+        [type_1.RType.ForLoop]: n => this.foldRForLoop(n),
+        [type_1.RType.FunctionCall]: n => this.foldRFunctionCall(n),
+        [type_1.RType.FunctionDefinition]: n => this.foldRFunctionDefinition(n),
+        [type_1.RType.IfThenElse]: n => this.foldRIfThenElse(n),
+        [type_1.RType.LineDirective]: n => this.foldRLineDirective(n),
+        [type_1.RType.Logical]: n => this.foldRLogical(n),
+        [type_1.RType.Next]: n => this.foldRNext(n),
+        [type_1.RType.Number]: n => this.foldRNumber(n),
+        [type_1.RType.Parameter]: n => this.foldRParameter(n),
+        [type_1.RType.Pipe]: n => this.foldRPipe(n),
+        [type_1.RType.RepeatLoop]: n => this.foldRRepeatLoop(n),
+        [type_1.RType.String]: n => this.foldRString(n),
+        [type_1.RType.Symbol]: n => this.foldRSymbol(n),
+        [type_1.RType.UnaryOp]: n => this.foldRUnaryOp(n),
+        [type_1.RType.WhileLoop]: n => this.foldRWhileLoop(n),
+    };
+}
+exports.DefaultNormalizedAstFold = DefaultNormalizedAstFold;
+//# sourceMappingURL=normalized-ast-fold.js.map

package/cli/slicer-app.js

@@ -29,7 +29,7 @@ async function getSlice() {
     (0, assert_1.guard)(options.input !== undefined, 'input must be given');
     (0, assert_1.guard)(options.criterion !== undefined, 'a slicing criterion must be given');
     await slicer.init(options['input-is-text']
-        ? { request: 'text', content: options.input }
+        ? { request: 'text', content: options.input.replaceAll('\\n', '\n') }
         : { request: 'file', content: options.input }, options['no-magic-comments'] ? auto_select_defaults_1.doNotAutoSelect : (0, magic_comments_1.makeMagicCommentHandler)(auto_select_defaults_1.doNotAutoSelect));
     let mappedSlices = [];
     let reconstruct = undefined;

package/core/steps/pipeline/pipeline.d.ts

@@ -22,6 +22,16 @@ export interface Pipeline<T extends IPipelineStep = IPipelineStep> {
  * @see Pipeline for details
  */
 export type PipelineStepNames<P extends Pipeline> = PipelineStep<P>['name'];
+/**
+ * Returns the steps included in the given pipeline.
+ * @example
+ * ```ts
+ * type Pipeline = typeof DEFAULT_DATAFLOW_PIPELINE
+ * // Pipeline is now Pipeline<step1 | step2 | ...>
+ * type Steps = PipelineStep<typeof DEFAULT_DATAFLOW_PIPELINE>
+ * // Steps is now just step1 | step2 | ...
+ * ```
+ */
 export type PipelineStep<P extends Pipeline> = P extends Pipeline<infer U> ? U : never;
 /**
  * Meta-information attached to every step result
@@ -35,10 +45,51 @@ export interface PipelinePerStepMetaInformation {
         readonly timing: number;
     };
 }
+/**
+ * Returns the step with the given name from the given pipeline.
+ *
+ * @example
+ * ```ts
+ * type Foo = PipelineStepWithName<typeof DEFAULT_DATAFLOW_PIPELINE, 'parse'>
+ * // Foo is now only the "parse" step from the DEFAULT_DATAFLOW_PIPELINE
+ * ```
+ */
 export type PipelineStepWithName<P extends Pipeline, Name extends PipelineStepName> = P extends Pipeline<infer U> ? U extends IPipelineStep<Name> ? U : never : never;
+/**
+ * Returns the processor function of the step with the given name from the given pipeline.
+ * @see {@link PipelineStepWithName}
+ */
 export type PipelineStepProcessorWithName<P extends Pipeline, Name extends PipelineStepName> = PipelineStepWithName<P, Name>['processor'];
+/**
+ * Returns the printer function of the step with the given name from the given pipeline.
+ * @see {@link PipelineStepWithName}
+ */
 export type PipelineStepPrintersWithName<P extends Pipeline, Name extends PipelineStepName> = PipelineStepWithName<P, Name>['printer'];
+/**
+ * Returns the output type of the step with the given name from the given pipeline.
+ *
+ * @example
+ * ```ts
+ * type Foo = PipelineStepOutputWithName<typeof DEFAULT_DATAFLOW_PIPELINE, 'parse'>
+ * // Foo contains the ParseStepOutput & PipelinePerStepMetaInformation type (ie the parse output and meta information)
+ * @see {@link PipelineStepWithName}
+ * ```
+ */
 export type PipelineStepOutputWithName<P extends Pipeline, Name extends PipelineStepName> = Awaited<ReturnType<PipelineStepProcessorWithName<P, Name>>> & PipelinePerStepMetaInformation;
+/**
+ * Returns a union type that represents the required inputs to be passed to the given pipeline.
+ *
+ * @example
+ * ```ts
+ * type Foo = PipelineInput<typeof DEFAULT_DATAFLOW_PIPELINE>
+ * // Foo contains ParseRequiredInput & NormalizeRequiredInput
+ * ```
+ *
+ * In short, this can be useful whenever you want to describe _all_ inputs a complete
+ * pipeline needs to run through (i.e., the union of all inputs required by the individual steps).
+ *
+ * @see {@link PipelineOutput}
+ */
 export type PipelineInput<P extends Pipeline> = UnionToIntersection<PipelineStep<P>['requiredInput']>;
 /**
  * Only gets the union of 'requiredInput' of those PipelineSteps which have a 'execute' field of type 'OncePerRequest'.
@@ -47,6 +98,18 @@ export type PipelineInput<P extends Pipeline> = UnionToIntersection<PipelineStep
 export type PipelinePerRequestInput<P extends Pipeline> = {
     [K in PipelineStepNames<P>]: PipelineStepWithName<P, K>['executed'] extends PipelineStepStage.OncePerFile ? never : PipelineStepWithName<P, K>['requiredInput'];
 }[PipelineStepNames<P>];
+/**
+ * Returns an object type that represents the types of the outputs that will result from running the given pipeline, each as the step's name mapped to its PipelineStepOutputWithName.
+ * @example
+ * ```ts
+ * type Foo = PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>
+ * // Foo contains {
+ * //   parse: ParseStepOutput & PipelinePerStepMetaInformation,
+ * //   normalize: NormalizeStepOutput & PipelinePerStepMetaInformation,
+ * //   ...
+ * // }
+ * ```
+ */
 export type PipelineOutput<P extends Pipeline> = {
     [K in PipelineStepNames<P>]: PipelineStepOutputWithName<P, K>;
 };

package/dataflow/environments/default-builtin-config.js

@@ -83,7 +83,7 @@ exports.DefaultBuiltinConfig = [
             /* downloader and installer functions (R, devtools, BiocManager) */
             'library.dynam', 'install.packages', 'install', 'install_github', 'install_gitlab', 'install_bitbucket', 'install_url', 'install_git', 'install_svn', 'install_local', 'install_version', 'update_packages',
             /* weird env attachments */
-            'attach', 'detach', 'unname', 'rm', 'remove'
+            'attach', 'unname'
         ],
         processor: 'builtin:default',
         config: { hasUnknownSideEffects: true },

package/dataflow/environments/resolve-by-name.d.ts

@@ -13,3 +13,8 @@ import { ReferenceType } from './identifier';
  */
 export declare function resolveByName(name: Identifier, environment: REnvironmentInformation, target?: ReferenceType): IdentifierDefinition[] | undefined;
 export declare function resolvesToBuiltInConstant(name: Identifier | undefined, environment: REnvironmentInformation, wantedValue: unknown): Ternary;
+export interface ResolveResult<T = unknown> {
+    value: T;
+    from: ReferenceType;
+}
+export declare function resolveToConstants(name: Identifier | undefined, environment: REnvironmentInformation): ResolveResult[] | undefined;

package/dataflow/environments/resolve-by-name.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveByName = resolveByName;
 exports.resolvesToBuiltInConstant = resolvesToBuiltInConstant;
+exports.resolveToConstants = resolveToConstants;
 const environment_1 = require("./environment");
 const identifier_1 = require("./identifier");
 const info_1 = require("../info");
@@ -80,4 +81,17 @@ function resolvesToBuiltInConstant(name, environment, wantedValue) {
         return some ? 1 /* Ternary.Maybe */ : 2 /* Ternary.Never */;
     }
 }
+function resolveToConstants(name, environment) {
+    if (name === undefined) {
+        return undefined;
+    }
+    const definitions = resolveByName(name, environment, identifier_1.ReferenceType.Constant);
+    if (definitions === undefined) {
+        return undefined;
+    }
+    return definitions.map(def => ({
+        value: def.value,
+        from: def.type
+    }));
+}
 //# sourceMappingURL=resolve-by-name.js.map

package/dataflow/internal/process/functions/call/built-in/built-in-expression-list.js

@@ -53,7 +53,7 @@ function updateSideEffectsForCalledFunctions(calledEnvs, inputEnvironment, nextG
     for (const { functionCall, called } of calledEnvs) {
         const callDependencies = nextGraph.getVertex(functionCall, true)?.controlDependencies;
         for (const calledFn of called) {
-            (0, assert_1.guard)(calledFn.tag === vertex_1.VertexType.FunctionDefinition, 'called function must call a function definition');
+            (0, assert_1.guard)(calledFn.tag === vertex_1.VertexType.FunctionDefinition, 'called function must be a function definition');
             // only merge the environments they have in common
             let environment = calledFn.environment;
             while (environment.level > inputEnvironment.level) {

package/dataflow/internal/process/functions/call/built-in/built-in-if-then-else.js

@@ -33,32 +33,42 @@ function processIfThenElse(name, args, rootId, data) {
     let then;
     let makeThenMaybe = false;
     // we should defer this to the abstract interpretation
-    const conditionIsFalse = (0, resolve_by_name_1.resolvesToBuiltInConstant)(condArg?.lexeme, data.environment, false);
-    const conditionIsTrue = (0, resolve_by_name_1.resolvesToBuiltInConstant)(condArg?.lexeme, data.environment, true);
-    if (conditionIsFalse !== 0 /* Ternary.Always */) {
+    const definitions = (0, resolve_by_name_1.resolveToConstants)(condArg?.lexeme, data.environment);
+    const conditionIsAlwaysFalse = definitions?.every(d => d.value === false) ?? false;
+    const conditionIsAlwaysTrue = definitions?.every(d => d.value === true) ?? false;
+    if (!conditionIsAlwaysFalse) {
         then = (0, processor_1.processDataflowFor)(thenArg, data);
         if (then.entryPoint) {
             then.graph.addEdge(name.info.id, then.entryPoint, edge_1.EdgeType.Returns);
         }
-        if (conditionIsTrue !== 0 /* Ternary.Always */) {
+        if (!conditionIsAlwaysTrue) {
             makeThenMaybe = true;
         }
     }
     let otherwise;
     let makeOtherwiseMaybe = false;
-    if (otherwiseArg !== undefined && conditionIsTrue !== 0 /* Ternary.Always */) {
+    if (otherwiseArg !== undefined && !conditionIsAlwaysTrue) {
         otherwise = (0, processor_1.processDataflowFor)(otherwiseArg, data);
         if (otherwise.entryPoint) {
             otherwise.graph.addEdge(name.info.id, otherwise.entryPoint, edge_1.EdgeType.Returns);
         }
-        if (conditionIsFalse !== 0 /* Ternary.Always */) {
+        if (!conditionIsAlwaysFalse) {
             makeOtherwiseMaybe = true;
         }
     }
     const nextGraph = cond.graph.mergeWith(then?.graph).mergeWith(otherwise?.graph);
     const thenEnvironment = then?.environment ?? cond.environment;
     // if there is no "else" case, we have to recover whatever we had before as it may be not executed
-    const finalEnvironment = (0, append_1.appendEnvironment)(thenEnvironment, otherwise ? otherwise.environment : cond.environment);
+    let finalEnvironment;
+    if (conditionIsAlwaysFalse) {
+        finalEnvironment = otherwise ? otherwise.environment : cond.environment;
+    }
+    else if (conditionIsAlwaysTrue) {
+        finalEnvironment = thenEnvironment;
+    }
+    else {
+        finalEnvironment = (0, append_1.appendEnvironment)(thenEnvironment, otherwise ? otherwise.environment : cond.environment);
+    }
     const cdTrue = { id: rootId, when: true };
     const cdFalse = { id: rootId, when: false };
     // again within an if-then-else we consider all actives to be read

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

@@ -1,4 +1,4 @@
-import type { DataflowGraph } from '../../dataflow/graph/graph';
+import type { DataflowGraph, UnknownSidEffect } from '../../dataflow/graph/graph';
 import type { RShell } from '../../r-bridge/shell';
 import type { MermaidMarkdownMark } from '../../util/mermaid/dfg';
 import { DEFAULT_DATAFLOW_PIPELINE } from '../../core/steps/pipeline/default-pipelines';
@@ -12,6 +12,7 @@ export interface PrintDataflowGraphOptions {
     readonly switchCodeAndGraph?: boolean;
     readonly hideEnvInMermaid?: boolean;
 }
+export declare function formatSideEffect(ef: UnknownSidEffect): string;
 export declare function printDfGraphForCode(shell: RShell, code: string, options: PrintDataflowGraphOptions & {
     exposeResult: true;
 }): Promise<[string, PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>]>;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printDfGraph = printDfGraph;
+exports.formatSideEffect = formatSideEffect;
 exports.printDfGraphForCode = printDfGraphForCode;
 exports.verifyExpectedSubgraph = verifyExpectedSubgraph;
 const dfg_1 = require("../../util/mermaid/dfg");
@@ -11,7 +12,6 @@ const decorate_1 = require("../../r-bridge/lang-4.x/ast/model/processing/decorat
 const resolve_graph_1 = require("../../dataflow/graph/resolve-graph");
 const diff_1 = require("../../dataflow/graph/diff");
 const assert_1 = require("../../util/assert");
-const json_1 = require("../../util/json");
 const time_1 = require("../../util/time");
 function printDfGraph(graph, mark) {
     return `
@@ -24,6 +24,14 @@ ${(0, dfg_1.graphToMermaid)({
 \`\`\`
 	`;
 }
+function formatSideEffect(ef) {
+    if (typeof ef === 'object') {
+        return `${ef.id} (linked)`;
+    }
+    else {
+        return `${ef}`;
+    }
+}
 async function printDfGraphForCode(shell, code, { mark, showCode = true, codeOpen = false, exposeResult, switchCodeAndGraph = false, hideEnvInMermaid = false } = {}) {
     const now = performance.now();
     const result = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_DATAFLOW_PIPELINE, {
@@ -48,7 +56,7 @@ ${code}
 <summary style="color:gray">${switchCodeAndGraph ? 'Dataflow Graph of the R Code' : 'R Code of the 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: ' + JSON.stringify(result.dataflow.graph.unknownSideEffects, json_1.jsonReplacer) + ')' : 'no unknown side effects'} during the analysis.
+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.
 
 ${switchCodeAndGraph ? dfGraph : codeText}
 

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

@@ -26,7 +26,7 @@ async function printNormalizedAstForCode(shell, code, { showCode = true, prefix
         request: (0, retriever_1.requestFromInput)(code)
     }).allRemainingSteps();
     const duration = performance.now() - now;
-    const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parsing) within the generation environment.`;
+    const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parsing with the R shell) within the generation environment.`;
     return '\n\n' + printNormalizedAst(result.normalize.ast, prefix) + (showCode ? `
 <details>
 

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

@@ -2,7 +2,7 @@ import ts from 'typescript';
 export interface TypeElementInSource {
     name: string;
     node: ts.Node;
-    kind: 'interface' | 'type' | 'enum';
+    kind: 'interface' | 'type' | 'enum' | 'class';
     extends: string[];
     generics: string[];
     filePath: string;

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

@@ -150,6 +150,27 @@ function collectHierarchyInformation(sourceFiles, options) {
                 })
             });
         }
+        else if (typescript_1.default.isClassDeclaration(node)) {
+            const className = node.name?.getText(sourceFile) ?? '';
+            const baseTypes = node.heritageClauses?.flatMap(clause => clause.types
+                .map(type => type.getText(sourceFile) ?? '')
+                .map(dropGenericsFromType)) ?? [];
+            const generics = node.typeParameters?.map(param => param.getText(sourceFile) ?? '') ?? [];
+            hierarchyList.push({
+                name: dropGenericsFromType(className),
+                node,
+                kind: 'class',
+                extends: baseTypes,
+                comments: getTextualComments(node),
+                generics,
+                filePath: sourceFile.fileName,
+                lineNumber: getStartLine(node, sourceFile),
+                properties: node.members.map(member => {
+                    const name = member.name?.getText(sourceFile) ?? '';
+                    return `${name}${(0, mermaid_1.escapeMarkdown)(': ' + getType(member, typeChecker))}`;
+                }),
+            });
+        }
         typescript_1.default.forEachChild(node, child => visit(child, sourceFile));
     };
     sourceFiles.forEach(sourceFile => {

package/documentation/print-dataflow-graph-wiki.js

@@ -841,6 +841,24 @@ ${await (0, doc_dfg_1.printDfGraphForCode)(shell, 'load("file")\nprint(x + y)')}
 
 In general, as we cannot handle these correctly, we leave it up to other analyses (and [queries](${doc_files_1.FlowrWikiBaseRef}/Query%20API)) to handle these cases
 as they see fit.
+
+#### Linked Unknown Side Effects
+
+Not all side effects are created equal in the sense that they stem from a specific function call.
+Consider R's basic [\`graphics\`](https://www.rdocumentation.org/packages/graphics/) which
+implicitly draws on the current device and does not explicitly link a function like \`points\` to the last call opening a new graphic device. In such a scenario, we use a linked side effect to mark the relation:
+
+${await (async () => {
+            const [result, df] = await (0, doc_dfg_1.printDfGraphForCode)(shell, 'plot(data)\npoints(data2)', { exposeResult: true });
+            return `
+${result}
+
+Such side effects are not marked explicitly (with a big edge) but they are part of the unknown side effects: [${[...df.dataflow.graph.unknownSideEffects].map(doc_dfg_1.formatSideEffect).join(',')}].
+Additionally, we express this by a ${linkEdgeName(edge_1.EdgeType.Reads)} edge.
+	`;
+        })()}
+ 
+
 	`;
     })()}
 

package/documentation/print-normalized-ast-wiki.js

@@ -13,11 +13,18 @@ const path_1 = __importDefault(require("path"));
 const doc_files_1 = require("./doc-util/doc-files");
 const doc_cli_option_1 = require("./doc-util/doc-cli-option");
 const time_1 = require("../util/time");
+const doc_structure_1 = require("./doc-util/doc-structure");
+const pipeline_executor_1 = require("../core/pipeline-executor");
+const retriever_1 = require("../r-bridge/retriever");
+const visitor_1 = require("../r-bridge/lang-4.x/ast/model/processing/visitor");
+const collect_1 = require("../r-bridge/lang-4.x/ast/model/collect");
+const normalized_ast_fold_1 = require("../abstract-interpretation/normalized-ast-fold");
 async function getText(shell) {
     const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
     const now = performance.now();
     const types = (0, doc_types_1.getTypesFromFolderAsMermaid)({
         rootFolder: path_1.default.resolve('./src/r-bridge/lang-4.x/ast/model/'),
+        files: [path_1.default.resolve('./src/abstract-interpretation/normalized-ast-fold.ts')],
         typeName: 'RNode',
         inlineTypes: doc_types_1.mermaidHide
     });
@@ -40,7 +47,7 @@ ${(0, doc_code_1.codeBlock)('r', 'x <- 2 * 3 + 1')}
 Each node in the AST contains the type, the id, and the lexeme (if applicable).
 Each edge is labeled with the type of the parent-child relationship (the "role").
 
-${await (0, doc_normalized_ast_1.printNormalizedAstForCode)(shell, 'x <- 2 * 3 + 1')}
+${await (0, doc_normalized_ast_1.printNormalizedAstForCode)(shell, 'x <- 2 * 3 + 1', { showCode: false, prefix: 'flowchart LR\n' })}
 
 &nbsp;
 
@@ -49,7 +56,7 @@ ${await (0, doc_normalized_ast_1.printNormalizedAstForCode)(shell, 'x <- 2 * 3 +
 > you can either use the [Visual Studio Code extension](${doc_files_1.FlowrGithubBaseRef}/vscode-flowr) or the ${(0, doc_cli_option_1.getReplCommand)('normalize*')} 
 > command in the REPL (see the [Interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface) for more information). 
 
-Indicative is the root expression list node, which is present in every normalized AST.
+Indicative of the normalization is the root expression list node, which is present in every normalized AST.
 In general, we provide node types for:
 
 1. literals (e.g., numbers and strings)
@@ -77,11 +84,106 @@ Most notably, the \`info\` field holds the \`id\` of the node, which is used to
 
 In summary, we have the following types:
 
-${(0, doc_types_1.printHierarchy)({ program: types.program, hierarchy: types.info, root: 'RNode', collapseFromNesting: Number.MAX_VALUE })}
+${(0, doc_structure_1.details)('Normalized AST Node Types', (0, doc_types_1.printHierarchy)({ program: types.program, hierarchy: types.info, root: 'RNode', collapseFromNesting: Number.MAX_VALUE }))}
 
-With this, the example file produced the following AST (shown from left to right for space reasons):
+The following segments intend to give you an overview of how to work with the normalized AST:
 
-${await (0, doc_normalized_ast_1.printNormalizedAstForCode)(shell, (0, doc_files_1.getFileContentFromRoot)('test/testfiles/example.R'), { prefix: 'flowchart LR\n' })}
+* [How to get a normalized AST](#how-get-a-normalized-ast)
+* [Visitors and Folds](#visitors-and-folds)
+
+## How Get a Normalized AST
+
+As explained alongside the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface#the-pipeline-executor) wiki page, you can use the 
+\`${pipeline_executor_1.PipelineExecutor.name}\` to get the normalized AST. If you are only interested in the normalization,
+a pipeline like the \`DEFAULT_NORMALIZE_PIPELINE\` suffices:
+
+${(0, doc_code_1.codeBlock)('ts', `
+async function getAst(code: string): Promise<RNode> {
+    const result = await new ${pipeline_executor_1.PipelineExecutor.name}(DEFAULT_NORMALIZE_PIPELINE, {
+        shell: new ${shell_1.RShell.name}(),
+        request: ${retriever_1.requestFromInput.name}(code.trim())
+    }).allRemainingSteps();
+    return result.normalize.ast;
+}`)}
+
+From the REPL, you can use the ${(0, doc_cli_option_1.getReplCommand)('normalize')} command. 
+
+## Traversing the Normalized AST
+
+We provide two ways to traverse the normalized AST: [Visitors](#visitors) and [Folds](#folds).
+
+### Visitors
+
+If you want a simple visitor which traverses the AST, the \`${visitor_1.visitAst.name}\` function from 
+${(0, doc_files_1.getFilePathMd)('../r-bridge/lang-4.x/ast/model/processing/visitor.ts')} is a good starting point.
+You may specify functions to be called whenever you enter and exit a node during the traversal, and any
+computation is to be done by side effects.
+For example, if you want to collect all the \`id\`s present within a normalized (sub-)ast,
+as it is done by the ${collect_1.collectAllIds.name} function, you can use the following visitor:
+
+${(0, doc_code_1.codeBlock)('ts', `
+const ids = new Set<NodeId>();
+visitAst(nodes, node => {
+    ids.add(node.info.id);
+});
+return ids;
+`)} 
+
+### Folds
+
+We formulate a fold with the base class \`${normalized_ast_fold_1.DefaultNormalizedAstFold.name}\` in ${(0, doc_files_1.getFilePathMd)('../abstract-interpretation/normalized-ast-fold.ts')}.
+Using this class, you can create your own fold behavior by overwriting the default methods.
+By default, the class provides a monoid abstraction using the _empty_ from the constructor and the _concat_ method.
+
+ 
+${(0, doc_types_1.printHierarchy)({ program: types.program, hierarchy: types.info, root: 'DefaultNormalizedAstFold' })}
+
+Now, of course, we could provide hundreds of examples here, but we use tests to verify that the fold behaves as expected
+and happily point to them at ${(0, doc_files_1.getFilePathMd)('../../test/functionality/r-bridge/normalize-ast-fold.test.ts')}.
+
+As a simple showcase, we want to use the fold to evaluate numeric expressions containing numbers, \`+\`, and \`*\` operators.
+
+${(0, doc_code_1.codeBlock)('ts', `
+class MyMathFold<Info> extends ${normalized_ast_fold_1.DefaultNormalizedAstFold.name}<number, Info> {
+    constructor() {
+    	/* use \`0\` as a placeholder empty for the monoid */
+        super(0);
+    }
+
+    protected override concat(a: number, b: number): number {
+    	/* for this example, we ignore cases that we cannot handle */ 
+        return b;
+    }
+
+    override foldRNumber(node: RNumber<Info>) {
+    	/* return the value of the number */ 
+        return node.content.num;
+    }
+
+    override foldRBinaryOp(node: RBinaryOp<Info>) {
+        if(node.operator === '+') {
+            return this.fold(node.lhs) + this.fold(node.rhs);
+        } else if(node.operator === '*') {
+            return this.fold(node.lhs) * this.fold(node.rhs);
+        } else {
+        	/* in case we cannot handle the operator we could throw an error, or just use the default behavior: */
+            return super.foldRBinaryOp(node);
+        }
+    }
+}
+`)}
+
+Now, we can use the \`${pipeline_executor_1.PipelineExecutor.name}\` to get the normalized AST and apply the fold:
+  
+${(0, doc_code_1.codeBlock)('ts', `
+const shell = new ${shell_1.RShell.name}();
+const ast = (await new ${pipeline_executor_1.PipelineExecutor.name}(DEFAULT_NORMALIZE_PIPELINE, {
+	shell, request: retrieveNormalizedAst(${shell_1.RShell.name}, '1 + 3 * 2')
+}).allRemainingSteps()).normalize.ast;
+
+const result = new MyMathFold().fold(ast);
+console.log(result); // -> 7
+`)}
 
 `;
 }

package/documentation/print-query-wiki.js

@@ -47,6 +47,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\`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.1.7",
+  "version": "2.1.8",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -41,7 +41,7 @@
     "performance-test": "func() { cd test/performance/ && bash run-all-suites.sh $1 $2 $3; cd ../../; }; func",
     "test-full": "npm run test:coverage -- --no-watch -- --make-summary --test-installation",
     "detect-circular-deps": "npx madge  --extensions ts,tsx --circular src/",
-    "checkup": "npm run flowr -- --execute \":version\" && npm run lint && npm run test-full -- --forbid-only && docker build -t test-flowr -f scripts/Dockerfile . && npm run doc && npm-run-all wiki:*"
+    "checkup": "npm run flowr -- --execute \":version\" && npm run lint && npm run test-full -- --allowOnly=false && docker build -t test-flowr -f scripts/Dockerfile . && npm run doc && npm-run-all wiki:*"
   },
   "keywords": [
     "static code analysis",

package/queries/catalog/call-context-query/call-context-query-executor.js

@@ -51,6 +51,10 @@ function promoteQueryCallNames(queries) {
                 ...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 */
@@ -62,7 +66,11 @@ function promoteQueryCallNames(queries) {
             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)
+                }
             };
         }
     });
@@ -132,6 +140,15 @@ function removeIdenticalDuplicates(collector) {
         }
     }
 }
+function doesFilepathMatch(file, filter) {
+    if (filter === undefined) {
+        return true;
+    }
+    if (file === undefined) {
+        return filter.includeUndefinedFiles ?? true;
+    }
+    return filter.filter.test(file);
+}
 /**
  * Multi-stage call context query resolve.
  *
@@ -174,6 +191,10 @@ function executeCallContextQueries({ graph, ast }, queries) {
             }
         }
         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 = undefined;
             if (query.callTargets) {
                 targets = (0, identify_link_to_last_call_relation_1.satisfiesCallTargets)(nodeId, graph, query.callTargets);

package/queries/catalog/call-context-query/call-context-query-format.d.ts

@@ -6,10 +6,20 @@ import Joi from 'joi';
 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?
      */
@@ -27,6 +37,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>;
 }
 /**
  * Links the current call to the last call of the given kind.

package/queries/catalog/call-context-query/call-context-query-format.js

@@ -26,6 +26,10 @@ exports.CallContextQueryDefinition = {
         subkind: joi_1.default.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_1.default.string().valid(...Object.values(identify_link_to_last_call_relation_1.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_1.default.boolean().optional().description('Consider a case like `f <- function_of_interest`, do you want uses of `f` to be included in the results?'),
+        fileFilter: joi_1.default.object({
+            fileFilter: joi_1.default.string().required().description('Regex that a node\'s file attribute must match to be considered'),
+            includeUndefinedFiles: joi_1.default.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_1.default.object({
             type: joi_1.default.string().valid('link-to-last-call').required().description('The type of the linkTo sub-query.'),
             callName: joi_1.default.string().required().description('Regex regarding the function name of the last call. Similar to `callName`, strings are interpreted as a regular expression.')

package/r-bridge/lang-4.x/ast/model/processing/visitor.d.ts

@@ -4,7 +4,7 @@ export type OnEnter<OtherInfo> = (node: RNode<OtherInfo>) => (boolean | void);
 /** Similar to {@link OnEnter} but called when leaving a node. Can't stop exploration as the subtree is already visited! */
 export type OnExit<OtherInfo> = (node: RNode<OtherInfo>) => void;
 /**
- * Collects all node ids within a tree given by a respective root node
+ * Visits all node ids within a tree given by a respective root node using a depth-first search with prefix order.
  *
  * @param nodes          - The root id nodes to start collecting from
  * @param onVisit        - Called before visiting the subtree of each node. Can be used to stop visiting the subtree starting with this node (return `true` stop)

package/r-bridge/lang-4.x/ast/model/processing/visitor.js

@@ -100,7 +100,7 @@ class NodeVisitor {
     }
 }
 /**
- * Collects all node ids within a tree given by a respective root node
+ * Visits all node ids within a tree given by a respective root node using a depth-first search with prefix order.
  *
  * @param nodes          - The root id nodes to start collecting from
  * @param onVisit        - Called before visiting the subtree of each node. Can be used to stop visiting the subtree starting with this node (return `true` stop)

package/r-bridge/lang-4.x/ast/parser/json/format.js

@@ -10,10 +10,10 @@ exports.RootId = 0;
 function prepareParsedData(data) {
     let json;
     try {
-        json = JSON.parse(`[${data}]`);
+        json = JSON.parse(`[${data.trim()}]`);
     }
     catch (e) {
-        throw new Error(`Failed to parse data ${data}: ${e?.message}`);
+        throw new Error(`Failed to parse data [${data}]: ${e?.message}`);
     }
     (0, assert_1.guard)(Array.isArray(json), () => `Expected ${data} to be an array but was not`);
     const ret = new Map(json.map(([line1, col1, line2, col2, id, parent, token, terminal, text]) => {

package/reconstruct/reconstruct.js

@@ -277,7 +277,7 @@ function reconstructParameter(parameter, name, defaultValue, configuration) {
         return plain(`${getLexeme(parameter.name)}=${getLexeme(parameter.defaultValue)}`);
     }
     else if (parameter.defaultValue !== undefined && name.length === 0) {
-        return plain(getLexeme(parameter.defaultValue));
+        return defaultValue ?? [];
     }
     else {
         return name;

package/util/assert.d.ts

@@ -6,7 +6,7 @@ export declare function isNotNull<T>(x: T | null): x is T;
 export type GuardMessage = string | (() => string);
 /**
  * @param assertion - will be asserted
- * @param message - if a string, will be used as error message, if a function, will be called to produce the error message (can be used to avoid costly message generations)
+ * @param message - if a string, we will use it as the error message, if it is a function, we will call it to produce the error message (can be used to avoid costly message generations)
  * @throws GuardError - if the assertion fails
  */
 export declare function guard(assertion: boolean | undefined, message?: GuardMessage): asserts assertion;

package/util/assert.js

@@ -6,7 +6,7 @@ exports.isNotUndefined = isNotUndefined;
 exports.isUndefined = isUndefined;
 exports.isNotNull = isNotNull;
 exports.guard = guard;
-/* istanbul ignore next */
+/* v8 ignore next */
 function assertUnreachable(x) {
     throw new Error(`Unexpected object: ${JSON.stringify(x)}`);
 }
@@ -27,10 +27,11 @@ class GuardError extends Error {
 }
 /**
  * @param assertion - will be asserted
- * @param message - if a string, will be used as error message, if a function, will be called to produce the error message (can be used to avoid costly message generations)
+ * @param message - if a string, we will use it as the error message, if it is a function, we will call it to produce the error message (can be used to avoid costly message generations)
  * @throws GuardError - if the assertion fails
  */
 function guard(assertion, message = 'Assertion failed') {
+    /* v8 ignore next 3 */
     if (!assertion) {
         throw new GuardError(typeof message === 'string' ? message : message());
     }

package/util/version.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.flowrVersion = flowrVersion;
 const semver_1 = require("semver");
 // this is automatically replaced with the current version by release-it
-const version = '2.1.7';
+const version = '2.1.8';
 function flowrVersion() {
     return new semver_1.SemVer(version);
 }