@eagleoutice/flowr 2.0.25 → 2.1.0

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

@@ -0,0 +1,72 @@
+import type { BaseQueryFormat, BaseQueryResult } from '../base-query-format';
+import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
+export declare enum CallTargets {
+    /** call targets a function that is not defined locally (e.g., the call targets a library function) */
+    OnlyGlobal = "global",
+    /** call targets a function that is defined locally or globally, but must include a global function */
+    MustIncludeGlobal = "must-include-global",
+    /** call targets a function that is defined locally  */
+    OnlyLocal = "local",
+    /** call targets a function that is defined locally or globally, but must include a local function */
+    MustIncludeLocal = "must-include-local",
+    /** call targets a function that is defined locally or globally */
+    Any = "any"
+}
+export interface DefaultCallContextQueryFormat<CallName 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;
+    /** kind may be a step or anything that you attach to the call, this can be used to group calls together (e.g., linking `ggplot` to `visualize`). Defaults to `.` */
+    readonly kind?: string;
+    /** subkinds are used to uniquely identify the respective call type when grouping the output (e.g., the normalized name, linking `ggplot` to `plot`). Defaults to `.` */
+    readonly subkind?: string;
+    /**
+     * Call targets the function may have. This defaults to {@link CallTargets#Any}.
+     * Request this specifically to gain all call targets we can resolve.
+     */
+    readonly callTargets?: CallTargets;
+    /**
+     * Consider a case like `f <- function_of_interest`, do you want uses of `f` to be included in the results?
+     */
+    readonly includeAliases?: boolean;
+}
+/**
+ * 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.
+ * For now, this uses the static Control-Flow-Graph produced by flowR as the FD over-approximation is still not stable (see #1005).
+ * In short, this means that we are unable to detect origins over function call boundaries but plan on being more precise in the future.
+ */
+interface LinkToLastCall<CallName extends RegExp | string = RegExp | string> extends BaseQueryFormat {
+    readonly type: 'link-to-last-call';
+    /** Regex regarding the function name of the last call. Similar to {@link DefaultCallContextQueryFormat#callName}, strings are interpreted as a `RegExp`. */
+    readonly callName: CallName;
+}
+type LinkTo<CallName extends RegExp | string> = LinkToLastCall<CallName>;
+export interface SubCallContextQueryFormat<CallName extends RegExp | string = RegExp | string> extends DefaultCallContextQueryFormat<CallName> {
+    readonly linkTo: LinkTo<CallName>;
+}
+export interface CallContextQuerySubKindResult {
+    /** The id of the call vertex identified within the supplied dataflow graph */
+    readonly id: NodeId;
+    /**
+     * Ids of functions which are called by the respective function call,
+     * this will only be populated whenever you explicitly state the {@link DefaultCallContextQueryFormat#callTargets}.
+     * An empty array means that the call targets only non-local functions.
+     */
+    readonly calls?: readonly NodeId[];
+    /** ids attached by the linkTo query */
+    readonly linkedIds?: readonly NodeId[];
+    /**
+     * (Direct) alias locations this call stems from
+     */
+    readonly aliasRoots?: readonly NodeId[];
+}
+export type CallContextQueryKindResult = Record<string, {
+    /** maps each subkind to the results found, to be freely in the result form, this is mutable */
+    subkinds: Record<string, CallContextQuerySubKindResult[]>;
+}>;
+export interface CallContextQueryResult extends BaseQueryResult {
+    readonly kinds: CallContextQueryKindResult;
+}
+export type CallContextQuery<CallName extends RegExp | string = RegExp | string> = DefaultCallContextQueryFormat<CallName> | SubCallContextQueryFormat<CallName>;
+export {};

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallTargets = void 0;
+var CallTargets;
+(function (CallTargets) {
+    /** call targets a function that is not defined locally (e.g., the call targets a library function) */
+    CallTargets["OnlyGlobal"] = "global";
+    /** call targets a function that is defined locally or globally, but must include a global function */
+    CallTargets["MustIncludeGlobal"] = "must-include-global";
+    /** call targets a function that is defined locally  */
+    CallTargets["OnlyLocal"] = "local";
+    /** call targets a function that is defined locally or globally, but must include a local function */
+    CallTargets["MustIncludeLocal"] = "must-include-local";
+    /** call targets a function that is defined locally or globally */
+    CallTargets["Any"] = "any";
+})(CallTargets || (exports.CallTargets = CallTargets = {}));
+//# sourceMappingURL=call-context-query-format.js.map

package/queries/query-schema.d.ts

@@ -0,0 +1,7 @@
+import Joi from 'joi';
+export declare const CallContextQuerySchema: Joi.ObjectSchema<any>;
+export declare const SupportedQueriesSchema: Joi.AlternativesSchema<any>;
+export declare const CompoundQuerySchema: Joi.ObjectSchema<any>;
+export declare const VirtualQuerySchema: Joi.AlternativesSchema<any>;
+export declare const AnyQuerySchema: Joi.AlternativesSchema<any>;
+export declare const QueriesSchema: Joi.ArraySchema<any[]>;

package/queries/query-schema.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueriesSchema = exports.AnyQuerySchema = exports.VirtualQuerySchema = exports.CompoundQuerySchema = exports.SupportedQueriesSchema = exports.CallContextQuerySchema = void 0;
+const joi_1 = __importDefault(require("joi"));
+const call_context_query_format_1 = require("./call-context-query/call-context-query-format");
+exports.CallContextQuerySchema = joi_1.default.object({
+    type: joi_1.default.string().valid('call-context').required().description('The type of the query.'),
+    callName: joi_1.default.string().required().description('Regex regarding the function name!'),
+    kind: joi_1.default.string().optional().description('The kind of the call, this can be used to group calls together (e.g., linking `plot` to `visualize`). Defaults to `.`'),
+    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(call_context_query_format_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?'),
+    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.')
+    }).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.')
+}).description('Call context query used to find calls in the dataflow graph');
+exports.SupportedQueriesSchema = joi_1.default.alternatives(exports.CallContextQuerySchema).description('Supported queries');
+exports.CompoundQuerySchema = joi_1.default.object({
+    type: joi_1.default.string().valid('compound').required().description('The type of the query.'),
+    query: joi_1.default.string().required().description('The query to run on the file analysis information.'),
+    commonArguments: joi_1.default.object().required().description('Common arguments for all queries.'),
+    arguments: joi_1.default.array().items(joi_1.default.object()).required().description('Arguments for each query.')
+}).description('Compound query used to combine queries of the same type');
+exports.VirtualQuerySchema = joi_1.default.alternatives(exports.CompoundQuerySchema).description('Virtual queries (used for structure)');
+exports.AnyQuerySchema = joi_1.default.alternatives(exports.SupportedQueriesSchema, exports.VirtualQuerySchema).description('Any query');
+exports.QueriesSchema = joi_1.default.array().items(exports.AnyQuerySchema).description('Queries to run on the file analysis information (in the form of an array)');
+//# sourceMappingURL=query-schema.js.map

package/queries/query.d.ts

@@ -0,0 +1,35 @@
+import type { CallContextQuery } from './call-context-query/call-context-query-format';
+import type { DataflowGraph } from '../dataflow/graph/graph';
+import type { BaseQueryFormat, BaseQueryResult } from './base-query-format';
+import { executeCallContextQueries } from './call-context-query/call-context-query-executor';
+import type { VirtualQueryArgumentsWithType } from './virtual-query/virtual-queries';
+import type { VirtualCompoundConstraint } from './virtual-query/compound-query';
+import type { NormalizedAst } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
+export type Query = CallContextQuery;
+export type QueryArgumentsWithType<QueryType extends BaseQueryFormat['type']> = Query & {
+    type: QueryType;
+};
+export interface BasicQueryData {
+    readonly ast: NormalizedAst;
+    readonly graph: DataflowGraph;
+}
+export type QueryExecutor<Query extends BaseQueryFormat, Result extends BaseQueryResult> = (data: BasicQueryData, query: readonly Query[]) => Result;
+type SupportedQueries = {
+    [QueryType in Query['type']]: QueryExecutor<QueryArgumentsWithType<QueryType>, BaseQueryResult>;
+};
+export declare const SupportedQueries: {
+    readonly 'call-context': typeof executeCallContextQueries;
+};
+export type SupportedQueryTypes = keyof typeof SupportedQueries;
+export type QueryResult<Type extends Query['type']> = ReturnType<typeof SupportedQueries[Type]>;
+export declare function executeQueriesOfSameType<SpecificQuery extends Query>(data: BasicQueryData, ...queries: readonly SpecificQuery[]): QueryResult<SpecificQuery['type']>;
+export type QueryResults<Base extends SupportedQueryTypes> = {
+    readonly [QueryType in Base]: QueryResult<QueryType>;
+} & BaseQueryResult;
+type OmitFromValues<T, K extends string | number | symbol> = {
+    [P in keyof T]: Omit<T[P], K>;
+};
+export type QueryResultsWithoutMeta<Queries extends Query> = OmitFromValues<Omit<QueryResults<Queries['type']>, '.meta'>, '.meta'>;
+export type Queries<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>> = readonly (QueryArgumentsWithType<Base> | VirtualQueryArgumentsWithType<Base, VirtualArguments>)[];
+export declare function executeQueries<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(data: BasicQueryData, queries: Queries<Base, VirtualArguments>): QueryResults<Base>;
+export {};

package/queries/query.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SupportedQueries = void 0;
+exports.executeQueriesOfSameType = executeQueriesOfSameType;
+exports.executeQueries = executeQueries;
+const call_context_query_executor_1 = require("./call-context-query/call-context-query-executor");
+const assert_1 = require("../util/assert");
+const virtual_queries_1 = require("./virtual-query/virtual-queries");
+exports.SupportedQueries = {
+    'call-context': call_context_query_executor_1.executeCallContextQueries
+};
+function executeQueriesOfSameType(data, ...queries) {
+    (0, assert_1.guard)(queries.length > 0, 'At least one query must be provided');
+    /* every query must have the same type */
+    (0, assert_1.guard)(queries.every(q => q.type === queries[0].type), 'All queries must have the same type');
+    const executor = exports.SupportedQueries[queries[0].type];
+    (0, assert_1.guard)(executor !== undefined, `Unsupported query type: ${queries[0].type}`);
+    return executor(data, queries);
+}
+function isVirtualQuery(query) {
+    return virtual_queries_1.SupportedVirtualQueries[query.type] !== undefined;
+}
+function groupQueriesByType(queries) {
+    const grouped = {};
+    function addQuery(query) {
+        if (grouped[query.type] === undefined) {
+            grouped[query.type] = [];
+        }
+        grouped[query.type].push(query);
+    }
+    for (const query of queries) {
+        if (isVirtualQuery(query)) {
+            const executor = virtual_queries_1.SupportedVirtualQueries[query.type];
+            const subQueries = executor(query);
+            for (const subQuery of subQueries) {
+                addQuery(subQuery);
+            }
+        }
+        else {
+            addQuery(query);
+        }
+    }
+    return grouped;
+}
+function executeQueries(data, queries) {
+    const now = Date.now();
+    const grouped = groupQueriesByType(queries);
+    const results = {};
+    for (const type of Object.keys(grouped)) {
+        results[type] = executeQueriesOfSameType(data, ...grouped[type]);
+    }
+    results['.meta'] = {
+        timing: Date.now() - now
+    };
+    return results;
+}
+//# sourceMappingURL=query.js.map

package/queries/two-layer-collector.d.ts

@@ -0,0 +1,8 @@
+/** two layer map abstraction */
+export declare class TwoLayerCollector<Layer1 extends string, Layer2 extends string, Values> {
+    readonly store: Map<Layer1, Map<Layer2, Values[]>>;
+    add(layer1: Layer1, layer2: Layer2, value: Values): void;
+    get(layer1: Layer1, layer2: Layer2): Values[] | undefined;
+    outerKeys(): Iterable<Layer1>;
+    innerKeys(layer1: Layer1): Iterable<Layer2>;
+}

package/queries/two-layer-collector.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwoLayerCollector = void 0;
+/** two layer map abstraction */
+class TwoLayerCollector {
+    store = new Map();
+    add(layer1, layer2, value) {
+        let layer2Map = this.store.get(layer1);
+        if (layer2Map === undefined) {
+            layer2Map = new Map();
+            this.store.set(layer1, layer2Map);
+        }
+        let values = layer2Map.get(layer2);
+        if (values === undefined) {
+            values = [];
+            layer2Map.set(layer2, values);
+        }
+        values.push(value);
+    }
+    get(layer1, layer2) {
+        return this.store.get(layer1)?.get(layer2);
+    }
+    outerKeys() {
+        return this.store.keys();
+    }
+    innerKeys(layer1) {
+        return this.store.get(layer1)?.keys() ?? [];
+    }
+}
+exports.TwoLayerCollector = TwoLayerCollector;
+//# sourceMappingURL=two-layer-collector.js.map

package/queries/virtual-query/compound-query.d.ts

@@ -0,0 +1,24 @@
+import type { QueryArgumentsWithType, SupportedQueryTypes } from '../query';
+import type { BaseQueryFormat } from '../base-query-format';
+import type { StrictOmit } from 'ts-essentials';
+/** @see CompoundQueryFormat */
+export type VirtualCompoundConstraint<SubQueryType extends SupportedQueryTypes> = keyof StrictOmit<QueryArgumentsWithType<SubQueryType>, 'type'>;
+/**
+ * Virtual Query Format.
+ * Grouping query parameters of the same type (re-specified in the `query` field).
+ */
+export interface CompoundQueryFormat<SubQueryType extends SupportedQueryTypes, CommonArguments extends VirtualCompoundConstraint<SubQueryType>> extends BaseQueryFormat {
+    readonly type: 'compound';
+    readonly query: SubQueryType;
+    /** defaults to use the same arguments for all queries */
+    readonly commonArguments: Pick<QueryArgumentsWithType<SubQueryType>, CommonArguments>;
+    /**
+     * You do not have to re-state the type, this is automatically filled with the type for 'query'
+     * Additionally all arguments given in `commonArguments` are now enforced optional.
+     */
+    readonly arguments: ReadonlyArray<StrictOmit<StrictOmit<QueryArgumentsWithType<SubQueryType>, 'type'>, CommonArguments> & Partial<QueryArgumentsWithType<SubQueryType>>>;
+}
+/**
+ * Execute a single, virtual compound query in terms of unfolding the contained queries.
+ */
+export declare function executeCompoundQueries<SubQueryType extends SupportedQueryTypes, CommonArguments extends VirtualCompoundConstraint<SubQueryType> = VirtualCompoundConstraint<SubQueryType>>(query: CompoundQueryFormat<SubQueryType, CommonArguments>): QueryArgumentsWithType<SubQueryType>[];

package/queries/virtual-query/compound-query.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeCompoundQueries = executeCompoundQueries;
+/**
+ * Execute a single, virtual compound query in terms of unfolding the contained queries.
+ */
+function executeCompoundQueries(query) {
+    const results = [];
+    for (const arg of query.arguments) {
+        results.push({
+            type: query.query,
+            ...query.commonArguments,
+            ...arg
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=compound-query.js.map

package/queries/virtual-query/virtual-queries.d.ts

@@ -0,0 +1,15 @@
+import type { QueryArgumentsWithType, SupportedQueryTypes } from '../query';
+import type { CompoundQueryFormat, VirtualCompoundConstraint } from './compound-query';
+import { executeCompoundQueries } from './compound-query';
+import type { BaseQueryFormat } from '../base-query-format';
+/** A query that does not perform a search but may perform (e.g., convenience) modifications of other queries */
+export type VirtualQueryArgumentsWithType<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>> = CompoundQueryFormat<Base, VirtualArguments>;
+export type VirtualQueryExecutor<Query extends BaseQueryFormat, Result extends BaseQueryFormat[]> = (query: Query) => Result;
+type SupportedVirtualQueries = {
+    [QueryType in VirtualQueryArgumentsWithType<SupportedQueryTypes>['type']]: VirtualQueryExecutor<QueryArgumentsWithType<QueryType>, BaseQueryFormat[]>;
+};
+export declare const SupportedVirtualQueries: {
+    readonly compound: typeof executeCompoundQueries;
+};
+export type SupportedVirtualQueryTypes = keyof typeof SupportedVirtualQueries;
+export {};

package/queries/virtual-query/virtual-queries.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SupportedVirtualQueries = void 0;
+const compound_query_1 = require("./compound-query");
+exports.SupportedVirtualQueries = {
+    'compound': compound_query_1.executeCompoundQueries
+};
+//# sourceMappingURL=virtual-queries.js.map

package/r-bridge/data/data.d.ts

@@ -52,6 +52,11 @@ export declare const flowrCapabilities: {
                 readonly id: "environment-sharing";
                 readonly supported: "not";
                 readonly description: "_Handling side-effects by environments which are not copied when modified_";
+            }, {
+                readonly name: "Search Type";
+                readonly id: "search-type";
+                readonly supported: "fully";
+                readonly description: "_Separating the resolution for functions and symbols._";
             }, {
                 readonly name: "Search Path";
                 readonly id: "search-path";

package/r-bridge/data/data.js

@@ -68,6 +68,12 @@ exports.flowrCapabilities = {
                             supported: 'not',
                             description: '_Handling side-effects by environments which are not copied when modified_'
                         },
+                        {
+                            name: 'Search Type',
+                            id: 'search-type',
+                            supported: 'fully',
+                            description: '_Separating the resolution for functions and symbols._'
+                        },
                         {
                             name: 'Search Path',
                             id: 'search-path',

package/r-bridge/data/get.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAllCapabilities = exports.getCapabilityById = void 0;
+exports.getCapabilityById = getCapabilityById;
+exports.getAllCapabilities = getAllCapabilities;
 const assert_1 = require("../../util/assert");
 const data_1 = require("./data");
 function search(id, capabilities, path = []) {
@@ -30,7 +31,6 @@ function getCapabilityById(id) {
     capabilityCache.set(id, value);
     return value;
 }
-exports.getCapabilityById = getCapabilityById;
 function getAllCapabilities() {
     const result = [];
     function traverse(capabilities, currentPath = []) {
@@ -47,5 +47,4 @@ function getAllCapabilities() {
     traverse(data_1.flowrCapabilities.capabilities, []);
     return result;
 }
-exports.getAllCapabilities = getAllCapabilities;
 //# sourceMappingURL=get.js.map

package/r-bridge/init.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initCommand = exports.ErrorMarker = void 0;
+exports.ErrorMarker = void 0;
+exports.initCommand = initCommand;
 const convert_values_1 = require("./lang-4.x/convert-values");
 exports.ErrorMarker = 'err';
 /** Command(s) to be issued at the start of each shell */
@@ -19,5 +20,4 @@ function initCommand(eol) {
         /* error handling (just produce the marker) */
         + `},error=function(e){cat("${exports.ErrorMarker}")});cat(${(0, convert_values_1.ts2r)(eol)})},options=compiler::setCompilerOptions(optimize=3));`;
 }
-exports.initCommand = initCommand;
 //# sourceMappingURL=init.js.map

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.collectAllIds = void 0;
+exports.collectAllIds = collectAllIds;
 const visitor_1 = require("./processing/visitor");
 /**
  * Collects all node ids within a tree given by a respective root node
@@ -19,5 +19,4 @@ function collectAllIds(nodes, stop = () => false) {
     });
     return ids;
 }
-exports.collectAllIds = collectAllIds;
 //# sourceMappingURL=collect.js.map

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

@@ -1,7 +1,6 @@
 import type { SourceRange } from '../../../../util/range';
 import type { RType } from './type';
 import type { MergeableRecord } from '../../../../util/objects';
-import type { RNa, RNull } from '../../convert-values';
 import type { RNumber } from './nodes/r-number';
 import type { RString } from './nodes/r-string';
 import type { RLogical } from './nodes/r-logical';
@@ -108,7 +107,7 @@ export interface Namespace {
  * This subtype of {@link RNode} represents all types of constants
  * represented in the normalized AST.
  */
-export type RConstant<Info> = RNumber<Info> | RString<Info> | RLogical<Info> | RSymbol<Info, typeof RNull | typeof RNa>;
+export type RConstant<Info> = RNumber<Info> | RString<Info> | RLogical<Info>;
 /**
  * This subtype of {@link RNode} represents all types of {@link Leaf} nodes in the
  * normalized AST.

package/r-bridge/lang-4.x/ast/model/nodes/r-access.d.ts

@@ -11,6 +11,9 @@ interface RAccessBase<Info = NoInfo> extends Base<Info>, Location {
     accessed: RNode<Info>;
     operator: '[' | '[[' | '$' | '@';
 }
+/**
+ * Represents an R named access operation with `$` or `@`, the field is a string.
+ */
 export interface RNamedAccess<Info = NoInfo> extends RAccessBase<Info> {
     operator: '$' | '@';
     access: [RUnnamedArgument<Info>];

package/r-bridge/lang-4.x/ast/model/nodes/r-binary-op.d.ts

@@ -1,5 +1,8 @@
 import type { Base, Location, NoInfo, RNode } from '../model';
 import type { RType } from '../type';
+/**
+ * Operators like `+`, `==`, `&&`, etc.
+ */
 export interface RBinaryOp<Info = NoInfo> extends Base<Info>, Location {
     readonly type: RType.BinaryOp;
     operator: string;

package/r-bridge/lang-4.x/ast/model/nodes/r-break.d.ts

@@ -1,5 +1,8 @@
 import type { Leaf, Location, NoInfo } from '../model';
 import type { RType } from '../type';
+/**
+ * A `break` statement.
+ */
 export interface RBreak<Info = NoInfo> extends Location, Leaf<Info> {
     readonly type: RType.Break;
 }

package/r-bridge/lang-4.x/ast/model/nodes/r-comment.d.ts

@@ -1,5 +1,10 @@
 import type { Leaf, Location, NoInfo } from '../model';
 import type { RType } from '../type';
+/**
+ * ```r
+ * # I am a line comment
+ * ```
+ */
 export interface RComment<Info = NoInfo> extends Location, Leaf<Info> {
     readonly type: RType.Comment;
     content: string;

package/r-bridge/lang-4.x/ast/model/nodes/r-expression-list.d.ts

@@ -1,6 +1,10 @@
 import type { Base, Location, NoInfo, RNode, WithChildren } from '../model';
 import type { RType } from '../type';
 import type { RSymbol } from './r-symbol';
+/**
+ * Holds a list of expressions (and hence may be the root of an AST, summarizing all expressions in a file).
+ * The `grouping` property holds information on if the expression list is structural or created by a wrapper like `{}` or `()`.
+ */
 export interface RExpressionList<Info = NoInfo> extends WithChildren<Info, RNode<Info>>, Base<Info, string | undefined>, Partial<Location> {
     readonly type: RType.ExpressionList;
     /** encodes wrappers like `{}` or `()` */

package/r-bridge/lang-4.x/ast/model/nodes/r-for-loop.d.ts

@@ -3,7 +3,7 @@ import type { RType } from '../type';
 import type { RSymbol } from './r-symbol';
 import type { RExpressionList } from './r-expression-list';
 /**
- * ```ts
+ * ```r
  * for(<variable> in <vector>) <body>
  * ```
  */

package/r-bridge/lang-4.x/ast/model/nodes/r-function-definition.d.ts

@@ -1,9 +1,18 @@
 import type { Base, Location, NoInfo, RNode } from '../model';
 import type { RType } from '../type';
 import type { RParameter } from './r-parameter';
+/**
+ * ```r
+ * function(<parameters>) <body>
+ * ```
+ * or:
+ * ```r
+ * \(<parameters>) <body>
+ * ```
+ */
 export interface RFunctionDefinition<Info = NoInfo> extends Base<Info>, Location {
     readonly type: RType.FunctionDefinition;
-    /** the R formals, to our knowledge they must be unique */
+    /** the R formals, to our knowledge, they must be unique */
     parameters: RParameter<Info>[];
     body: RNode<Info>;
 }

package/r-bridge/lang-4.x/ast/model/nodes/r-if-then-else.d.ts

@@ -1,6 +1,11 @@
 import type { Base, Location, NoInfo, RNode } from '../model';
 import type { RType } from '../type';
 import type { RExpressionList } from './r-expression-list';
+/**
+ * ```r
+ * if(<condition>) <then> [else <otherwise>]
+ * ```
+ */
 export interface RIfThenElse<Info = NoInfo> extends Base<Info>, Location {
     readonly type: RType.IfThenElse;
     condition: RNode<Info>;

package/r-bridge/lang-4.x/ast/model/nodes/r-line-directive.d.ts

@@ -1,5 +1,8 @@
 import type { Leaf, Location, NoInfo } from '../model';
 import type { RType } from '../type';
+/**
+ * Special comment to signal line mappings (e.g., in generated code) to the interpreter.
+ */
 export interface RLineDirective<Info = NoInfo> extends Location, Leaf<Info> {
     readonly type: RType.LineDirective;
     line: number;

package/r-bridge/lang-4.x/ast/model/nodes/r-logical.d.ts

@@ -1,6 +1,9 @@
 import type { Leaf, Location, NoInfo } from '../model';
 import type { RType } from '../type';
 export type RLogicalValue = boolean;
+/**
+ * Represents logical values (`TRUE` or `FALSE`).
+ */
 export interface RLogical<Info = NoInfo> extends Leaf<Info>, Location {
     readonly type: RType.Logical;
     content: RLogicalValue;

package/r-bridge/lang-4.x/ast/model/nodes/r-next.d.ts

@@ -1,5 +1,8 @@
 import type { Leaf, Location, NoInfo } from '../model';
 import type { RType } from '../type';
+/**
+ * A `next` statement.
+ */
 export interface RNext<Info = NoInfo> extends Location, Leaf<Info> {
     readonly type: RType.Next;
 }

package/r-bridge/lang-4.x/ast/model/nodes/r-pipe.d.ts

@@ -1,5 +1,8 @@
 import type { Base, Location, NoInfo, RNode } from '../model';
 import type { RType } from '../type';
+/**
+ * Variant of the binary operator, specifically for the new, built-in pipe operator.
+ */
 export interface RPipe<Info = NoInfo> extends Base<Info>, Location {
     readonly type: RType.Pipe;
     readonly lhs: RNode<Info>;

package/r-bridge/lang-4.x/ast/model/nodes/r-repeat-loop.d.ts

@@ -2,7 +2,7 @@ import type { Base, Location, NoInfo } from '../model';
 import type { RType } from '../type';
 import type { RExpressionList } from './r-expression-list';
 /**
- * ```ts
+ * ```r
  * repeat <body>
  * ```
  */

package/r-bridge/lang-4.x/ast/model/nodes/r-string.d.ts

@@ -1,6 +1,9 @@
 import type { Leaf, Location, NoInfo } from '../model';
 import type { RType } from '../type';
 import type { RStringValue } from '../../../convert-values';
+/**
+ * Represents a string like `"hello"`, including raw strings like `r"(hello)"`.
+ */
 export interface RString<Info = NoInfo> extends Leaf<Info>, Location {
     readonly type: RType.String;
     content: RStringValue;

package/r-bridge/lang-4.x/ast/model/nodes/r-symbol.d.ts

@@ -1,6 +1,9 @@
 import type { Leaf, Location, Namespace, NoInfo } from '../model';
 import type { RType } from '../type';
 export declare function isSpecialSymbol(symbol: RSymbol): boolean;
+/**
+ * Represents identifiers (variables).
+ */
 export interface RSymbol<Info = NoInfo, T extends string = string> extends Leaf<Info>, Namespace, Location {
     readonly type: RType.Symbol;
     content: T;

package/r-bridge/lang-4.x/ast/model/nodes/r-symbol.js

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isSpecialSymbol = void 0;
+exports.isSpecialSymbol = isSpecialSymbol;
 const convert_values_1 = require("../../../convert-values");
 function isSpecialSymbol(symbol) {
     return symbol.content === convert_values_1.RNull || symbol.content === convert_values_1.RNa;
 }
-exports.isSpecialSymbol = isSpecialSymbol;
 //# sourceMappingURL=r-symbol.js.map

package/r-bridge/lang-4.x/ast/model/nodes/r-unary-op.d.ts

@@ -1,5 +1,8 @@
 import type { Base, Location, NoInfo, RNode } from '../model';
 import type { RType } from '../type';
+/**
+ * Unary operations like `+` and `-`
+ */
 export interface RUnaryOp<Info = NoInfo> extends Base<Info>, Location {
     readonly type: RType.UnaryOp;
     operator: string;