@eagleoutice/flowr 2.2.2 → 2.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -28,10 +28,12 @@
     "wiki:df-graph": "ts-node src/documentation/print-dataflow-graph-wiki.ts",
     "wiki:normalized-ast": "ts-node src/documentation/print-normalized-ast-wiki.ts",
     "wiki:query-api": "ts-node src/documentation/print-query-wiki.ts",
+    "wiki:core": "ts-node src/documentation/print-core-wiki.ts",
     "wiki:engines": "ts-node src/documentation/print-engines-wiki.ts",
     "wiki:search-api": "ts-node src/documentation/print-search-wiki.ts",
     "wiki:linting-and-testing": "ts-node src/documentation/print-linting-and-testing-wiki.ts",
     "wiki:interface": "ts-node src/documentation/print-interface-wiki.ts",
+    "gen:readme": "ts-node src/documentation/print-readme.ts",
     "build": "tsc --project .",
     "build-dev": "npm run build && npm run build:copy-wasm",
     "build:bundle-flowr": "npm run build && esbuild --bundle dist/src/cli/flowr.js --platform=node --bundle --minify --external:clipboardy --target=node22 --outfile=dist/src/cli/flowr.min.js && npm run build:copy-wasm-min",
@@ -47,7 +49,7 @@
     "performance-test": "func() { cd test/performance/ && bash run-all-suites.sh $1 $2 $3 $4; 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 -- --allowOnly=false && npm run test:system -- --no-watch && 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 && npm run test:system -- --no-watch && docker build -t test-flowr -f scripts/Dockerfile . && npm run doc && npm run gen:readme && npm-run-all wiki:*"
   },
   "keywords": [
     "static code analysis",
@@ -59,21 +61,6 @@
   ],
   "author": "Florian Sihler",
   "license": "ISC",
-  "eslintConfig": {
-    "settings": {
-      "import/resolver": {
-        "node": {
-          "extensions": [
-            ".ts"
-          ]
-        }
-      }
-    },
-    "extends": [
-      "@eagleoutice/eslint-config-flowr"
-    ],
-    "rules": {}
-  },
   "typedocOptions": {
     "includeVersion": true,
     "plugin": [
@@ -182,48 +169,50 @@
     }
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.3.0",
-    "@commitlint/config-angular": "^19.3.0",
-    "@eagleoutice/eslint-config-flowr": "^1.0.14",
-    "@j-ulrich/release-it-regex-bumper": "^5.1.0",
+    "@commitlint/cli": "^19.7.1",
+    "@commitlint/config-angular": "^19.7.1",
+    "@eagleoutice/eslint-config-flowr": "^1.0.17",
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.20.0",
+    "@j-ulrich/release-it-regex-bumper": "^5.2.0",
     "@types/command-line-args": "^5.2.3",
     "@types/command-line-usage": "^5.0.4",
     "@types/n-readlines": "^1.0.6",
-    "@types/n3": "^1.16.4",
+    "@types/n3": "^1.21.1",
     "@types/object-hash": "^3.0.6",
-    "@types/semver": "^7.5.6",
+    "@types/semver": "^7.5.8",
     "@types/tmp": "^0.2.6",
-    "@types/ws": "^8.5.10",
-    "@typescript-eslint/eslint-plugin": "^7.8.0",
-    "@vitest/coverage-v8": "^2.1.4",
-    "esbuild": "^0.23.1",
-    "eslint": "^8.57.1",
+    "@types/ws": "^8.5.14",
+    "@typescript-eslint/eslint-plugin": "^8.24.0",
+    "@vitest/coverage-v8": "^3.0.5",
+    "esbuild": "^0.25.0",
+    "eslint": "^9.20.1",
     "license-checker": "^25.0.1",
     "npm-run-all": "^4.1.5",
-    "release-it": "^17.6.0",
+    "release-it": "^18.1.2",
     "ts-node": "^10.9.2",
-    "typedoc": "^0.26.7",
-    "typedoc-plugin-missing-exports": "^3.0.0",
-    "typedoc-theme-hierarchy": "^5.0.3",
-    "typedoc-umlclass": "^0.10.0",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.4"
+    "typedoc": "^0.27.7",
+    "typedoc-plugin-missing-exports": "^3.1.0",
+    "typedoc-theme-hierarchy": "^5.0.4",
+    "typedoc-umlclass": "^0.10.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
   },
   "dependencies": {
-    "@xmldom/xmldom": "^0.9.2",
+    "@xmldom/xmldom": "^0.9.7",
     "clipboardy": "^4.0.0",
-    "command-line-args": "^6.0.0",
+    "command-line-args": "^6.0.1",
     "command-line-usage": "^7.0.3",
     "joi": "^17.13.3",
     "n-readlines": "^1.0.1",
-    "n3": "^1.21.3",
+    "n3": "^1.23.1",
     "object-hash": "^3.0.0",
     "object-sizeof": "^2.6.5",
-    "rotating-file-stream": "^3.2.5",
-    "semver": "^7.6.3",
+    "rotating-file-stream": "^3.2.6",
+    "semver": "^7.7.1",
     "tar": "^7.4.3",
     "tmp": "^0.2.3",
-    "ts-essentials": "^10.0.2",
+    "ts-essentials": "^10.0.4",
     "tslog": "^4.9.3",
     "web-tree-sitter": "^0.24.7",
     "ws": "^8.18.0",

package/queries/catalog/dependencies-query/dependencies-query-executor.js

@@ -12,7 +12,6 @@ const visitor_1 = require("../../../r-bridge/lang-4.x/ast/model/processing/visit
 const assert_1 = require("../../../util/assert");
 const objects_1 = require("../../../util/objects");
 const SupportedVertexTypes = [type_1.RType.String, type_1.RType.Logical, type_1.RType.Number];
-const Unknown = 'unknown';
 function executeDependenciesQuery(data, queries) {
     if (queries.length !== 1) {
         log_1.log.warn('Dependencies query expects only up to one query, but got ', queries.length, 'only using the first query');
@@ -26,10 +25,24 @@ function executeDependenciesQuery(data, queries) {
     const writeFunctions = getFunctionsToCheck(query.writeFunctions, ignoreDefault, dependencies_query_format_1.WriteFunctions);
     const numberOfFunctions = libraryFunctions.length + sourceFunctions.length + readFunctions.length + writeFunctions.length;
     const results = numberOfFunctions === 0 ? { kinds: {}, '.meta': { timing: 0 } } : (0, query_1.executeQueriesOfSameType)(data, ...makeCallContextQuery(libraryFunctions, 'library'), ...makeCallContextQuery(sourceFunctions, 'source'), ...makeCallContextQuery(readFunctions, 'read'), ...makeCallContextQuery(writeFunctions, 'write'));
-    const libraries = getResults(data, results, 'library', libraryFunctions, (id, vertex, argument) => ({
+    const getLexeme = (argument, id) => {
+        if ((argument && argument !== dependencies_query_format_1.Unknown) || !id) {
+            return undefined;
+        }
+        let get = data.ast.idMap.get(id);
+        if (!get) {
+            return undefined;
+        }
+        if (get.type === type_1.RType.Argument) {
+            get = get.value;
+        }
+        return get?.info.fullLexeme ?? get?.lexeme;
+    };
+    const libraries = getResults(data, results, 'library', libraryFunctions, (id, vertex, argId, argument) => ({
         nodeId: id,
         functionName: vertex.name,
-        libraryName: argument ?? Unknown
+        lexemeOfArgument: getLexeme(argument, argId),
+        libraryName: argument ?? dependencies_query_format_1.Unknown
     }), [type_1.RType.Symbol]);
     if (!ignoreDefault) {
         /* for libraries, we have to additionally track all uses of `::` and `:::`, for this we currently simply traverse all uses */
@@ -44,24 +57,27 @@ function executeDependenciesQuery(data, queries) {
             }
         });
     }
-    const sourcedFiles = getResults(data, results, 'source', sourceFunctions, (id, vertex, argument, linkedIds) => ({
+    const sourcedFiles = getResults(data, results, 'source', sourceFunctions, (id, vertex, argId, argument, linkedIds) => ({
         nodeId: id,
         functionName: vertex.name,
-        file: argument ?? Unknown,
-        linkedIds: (linkedIds?.length ?? 0) > 0 ? linkedIds : undefined
+        file: argument ?? dependencies_query_format_1.Unknown,
+        lexemeOfArgument: getLexeme(argument, argId),
+        linkedIds: linkedIds?.length ? linkedIds : undefined
     }));
-    const readData = getResults(data, results, 'read', readFunctions, (id, vertex, argument, linkedIds) => ({
+    const readData = getResults(data, results, 'read', readFunctions, (id, vertex, argId, argument, linkedIds) => ({
         nodeId: id,
         functionName: vertex.name,
-        source: argument ?? Unknown,
-        linkedIds: (linkedIds?.length ?? 0) > 0 ? linkedIds : undefined
+        source: argument ?? dependencies_query_format_1.Unknown,
+        lexemeOfArgument: getLexeme(argument, argId),
+        linkedIds: linkedIds?.length ? linkedIds : undefined
     }));
-    const writtenData = getResults(data, results, 'write', writeFunctions, (id, vertex, argument, linkedIds) => ({
+    const writtenData = getResults(data, results, 'write', writeFunctions, (id, vertex, argId, argument, linkedIds) => ({
         nodeId: id,
         functionName: vertex.name,
         // write functions that don't have argIndex are assumed to write to stdout
-        destination: argument ?? ((linkedIds?.length ?? 0) > 0 ? Unknown : 'stdout'),
-        linkedIds: (linkedIds?.length ?? 0) > 0 ? linkedIds : undefined
+        destination: argument ?? (linkedIds?.length ? dependencies_query_format_1.Unknown : 'stdout'),
+        lexemeOfArgument: getLexeme(argument, argId),
+        linkedIds: linkedIds?.length ? linkedIds : undefined
     }));
     return {
         '.meta': {
@@ -82,7 +98,8 @@ function makeCallContextQuery(functions, kind) {
     }));
 }
 function getResults(data, results, kind, functions, makeInfo, additionalAllowedTypes) {
-    return Object.entries(results?.kinds[kind]?.subkinds ?? {}).flatMap(([name, results]) => results.flatMap(({ id, linkedIds }) => {
+    const kindEntries = Object.entries(results?.kinds[kind]?.subkinds ?? {});
+    return kindEntries.flatMap(([name, results]) => results.flatMap(({ id, linkedIds }) => {
         const vertex = data.dataflow.graph.getVertex(id);
         const info = functions.find(f => f.name === name);
         let index = info.argIdx;
@@ -94,43 +111,58 @@ function getResults(data, results, kind, functions, makeInfo, additionalAllowedT
         }
         const args = index !== undefined ? getArgumentValue(data, vertex, index, additionalAllowedTypes) : undefined;
         if (!args) {
-            return (0, objects_1.compactRecord)(makeInfo(id, vertex, undefined, linkedIds));
+            const record = (0, objects_1.compactRecord)(makeInfo(id, vertex, undefined, undefined, linkedIds));
+            return record ? [record] : [];
         }
-        return args.flatMap(a => (0, objects_1.compactRecord)(makeInfo(id, vertex, a, linkedIds)));
-    })).filter(assert_1.isNotUndefined) ?? [];
-}
-function getArgumentValue({ dataflow: { graph } }, vertex, argumentIndex, additionalAllowedTypes) {
-    if (vertex) {
-        if (argumentIndex === 'unnamed') {
-            // return all unnamed arguments
-            const references = vertex.args.filter(arg => arg !== r_function_call_1.EmptyArgument && !arg.name).map(graph_1.getReferenceOfArgument);
-            return references.map(ref => {
-                if (!ref) {
-                    return undefined;
-                }
-                let valueNode = graph.idMap?.get(ref);
-                if (valueNode?.type === type_1.RType.Argument) {
-                    valueNode = valueNode.value;
-                }
-                if (valueNode) {
-                    const allowedTypes = [...SupportedVertexTypes, ...additionalAllowedTypes ?? []];
-                    return allowedTypes.includes(valueNode.type) ? (0, retriever_1.removeRQuotes)(valueNode.lexeme) : Unknown;
+        const results = [];
+        for (const [arg, values] of args.entries()) {
+            for (const value of values) {
+                const result = (0, objects_1.compactRecord)(makeInfo(id, vertex, arg, value, linkedIds));
+                if (result) {
+                    results.push(result);
                 }
-            });
+            }
         }
-        if (vertex.args.length > argumentIndex) {
-            const arg = (0, graph_1.getReferenceOfArgument)(vertex.args[argumentIndex]);
-            if (arg) {
-                let valueNode = graph.idMap?.get(arg);
-                if (valueNode?.type === type_1.RType.Argument) {
-                    valueNode = valueNode.value;
-                }
-                if (valueNode) {
-                    const allowedTypes = [...SupportedVertexTypes, ...additionalAllowedTypes ?? []];
-                    return [allowedTypes.includes(valueNode.type) ? (0, retriever_1.removeRQuotes)(valueNode.lexeme) : Unknown];
-                }
+        return results;
+    })) ?? [];
+}
+/**
+ * Get the values of all arguments matching the criteria.
+ */
+function getArgumentValue({ dataflow: { graph } }, vertex, argumentIndex, additionalAllowedTypes) {
+    if (!vertex) {
+        return undefined;
+    }
+    if (argumentIndex === 'unnamed') {
+        // return all unnamed arguments
+        const references = vertex.args.filter(arg => arg !== r_function_call_1.EmptyArgument && !arg.name).map(graph_1.getReferenceOfArgument).filter(assert_1.isNotUndefined);
+        const map = new Map();
+        for (const ref of references) {
+            let valueNode = graph.idMap?.get(ref);
+            if (valueNode?.type === type_1.RType.Argument) {
+                valueNode = valueNode.value;
+            }
+            if (valueNode) {
+                const allowedTypes = [...SupportedVertexTypes, ...additionalAllowedTypes ?? []];
+                const value = allowedTypes.includes(valueNode.type) ? (0, retriever_1.removeRQuotes)(valueNode.lexeme) : dependencies_query_format_1.Unknown;
+                map.set(ref, new Set([value]));
             }
         }
+        return map;
+    }
+    if (vertex.args.length > argumentIndex) {
+        const arg = (0, graph_1.getReferenceOfArgument)(vertex.args[argumentIndex]);
+        if (!arg) {
+            return undefined;
+        }
+        let valueNode = graph.idMap?.get(arg);
+        if (valueNode?.type === type_1.RType.Argument) {
+            valueNode = valueNode.value;
+        }
+        if (valueNode) {
+            const allowedTypes = [...SupportedVertexTypes, ...additionalAllowedTypes ?? []];
+            return new Map([[arg, new Set([allowedTypes.includes(valueNode.type) ? (0, retriever_1.removeRQuotes)(valueNode.lexeme) : dependencies_query_format_1.Unknown])]]);
+        }
     }
     return undefined;
 }

package/queries/catalog/dependencies-query/dependencies-query-format.d.ts

@@ -2,6 +2,7 @@ import type { BaseQueryFormat, BaseQueryResult } from '../../base-query-format';
 import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import Joi from 'joi';
 import { executeDependenciesQuery } from './dependencies-query-executor';
+export declare const Unknown = "unknown";
 export declare const LibraryFunctions: FunctionInfo[];
 export declare const SourceFunctions: FunctionInfo[];
 export declare const ReadFunctions: FunctionInfo[];
@@ -30,6 +31,8 @@ export interface DependencyInfo extends Record<string, unknown> {
     nodeId: NodeId;
     functionName: string;
     linkedIds?: readonly NodeId[];
+    /** the lexeme is presented whenever the specific info is of {@link Unknown} */
+    lexemeOfArgument?: string;
 }
 export type LibraryInfo = (DependencyInfo & {
     libraryName: 'unknown' | string;

package/queries/catalog/dependencies-query/dependencies-query-format.js

@@ -3,11 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DependenciesQueryDefinition = exports.WriteFunctions = exports.ReadFunctions = exports.SourceFunctions = exports.LibraryFunctions = void 0;
+exports.DependenciesQueryDefinition = exports.WriteFunctions = exports.ReadFunctions = exports.SourceFunctions = exports.LibraryFunctions = exports.Unknown = void 0;
 const ansi_1 = require("../../../util/ansi");
 const time_1 = require("../../../util/time");
 const joi_1 = __importDefault(require("joi"));
 const dependencies_query_executor_1 = require("./dependencies-query-executor");
+exports.Unknown = 'unknown';
 // these lists are originally based on https://github.com/duncantl/CodeDepends/blob/7fd96dfee16b252e5f642c77a7ababf48e9326f8/R/codeTypes.R
 exports.LibraryFunctions = [
     { name: 'library', argIdx: 0, argName: 'package' },
@@ -87,7 +88,7 @@ exports.ReadFunctions = [
     { name: 'Import', argIdx: 0, argName: 'file' },
 ];
 exports.WriteFunctions = [
-    { name: 'save', argIdx: 0, argName: '...' },
+    { name: 'save', argIdx: 2, argName: 'file' },
     { name: 'save.image', argIdx: 0, argName: 'file' },
     { name: 'write', argIdx: 1, argName: 'file' },
     { name: 'dput', argIdx: 1, argName: 'file' },

package/queries/catalog/happens-before-query/happens-before-query-format.js

@@ -22,6 +22,6 @@ exports.HappensBeforeQueryDefinition = {
         type: joi_1.default.string().valid('happens-before').required().description('The type of the query.'),
         a: joi_1.default.string().required().description('The first slicing criterion.'),
         b: joi_1.default.string().required().description('The second slicing criterion.')
-    }).description('The id map query retrieves the id map from the normalized AST.')
+    }).description('Happens-Before tracks whether a always happens before b.')
 };
 //# sourceMappingURL=happens-before-query-format.js.map

package/queries/catalog/resolve-value-query/resolve-value-query-executor.js

@@ -19,7 +19,7 @@ function executeResolveValueQuery({ dataflow: { graph, environment }, ast }, que
         }
         const values = query.criteria
             .map(criteria => (0, node_id_1.recoverName)((0, parse_1.slicingCriterionToId)(criteria, ast.idMap), ast.idMap))
-            .flatMap(ident => (0, resolve_by_name_1.resolveToValues)(ident, environment, graph));
+            .flatMap(ident => (0, resolve_by_name_1.resolveToValues)(ident, environment, graph.idMap ?? ast.idMap));
         results[key] = {
             values: [...new Set(values)]
         };

package/queries/catalog/resolve-value-query/resolve-value-query-format.js

@@ -44,6 +44,6 @@ exports.ResolveValueQueryDefinition = {
     schema: joi_1.default.object({
         type: joi_1.default.string().valid('resolve-value').required().description('The type of the query.'),
         criteria: joi_1.default.array().items(joi_1.default.string()).min(1).required().description('The slicing criteria to use.'),
-    }).description('Resolve Value query used to get definitions of an identifier')
+    }).description('The resolve value query used to get definitions of an identifier')
 };
 //# sourceMappingURL=resolve-value-query-format.js.map

package/queries/catalog/search-query/search-query-format.js

@@ -24,6 +24,6 @@ exports.SearchQueryDefinition = {
     schema: joi_1.default.object({
         type: joi_1.default.string().valid('search').required().description('The type of the query.'),
         search: joi_1.default.object().required().description('The search query to execute.')
-    }).description('The id map query retrieves the id map from the normalized AST.')
+    }).description('The search query searches the normalized AST and dataflow graph for nodes that match the given search query.')
 };
 //# sourceMappingURL=search-query-format.js.map

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

@@ -1,10 +1,12 @@
 export declare const flowrCapabilities: {
     readonly name: "Capabilities of flowR";
     readonly description: "This is an evolving representation of what started with #636 to formulate capabilities in a structured format.";
-    readonly version: "0.0.1";
+    readonly version: "0.0.2";
     readonly capabilities: readonly [{
         readonly name: "Names and Identifiers";
         readonly id: "names-and-identifiers";
+        readonly description: "The recognition of syntactical and non-syntactical names, including their resolutions to corresponding definitions.";
+        readonly example: (parser: import("../parser").KnownParser) => Promise<string>;
         readonly capabilities: readonly [{
             readonly name: "Form";
             readonly id: "form";
@@ -12,17 +14,41 @@ export declare const flowrCapabilities: {
                 readonly name: "Normal";
                 readonly id: "name-normal";
                 readonly supported: "fully";
-                readonly description: "_Recognize constructs like `a`, `plot`, ..._";
+                readonly description: "_Recognize symbol uses like `a`, `plot`, ..._  (i.e., \"normal variables or function calls\").";
+                readonly url: [{
+                    readonly name: string;
+                    readonly href: "https://adv-r.hadley.nz/names-values.html#binding-basics";
+                }, {
+                    readonly name: string;
+                    readonly href: "https://cran.r-project.org/doc/manuals/r-release/R-lang.html#Identifiers-1";
+                }];
             }, {
                 readonly name: "Quoted";
                 readonly id: "name-quoted";
                 readonly supported: "fully";
-                readonly description: "_Recognize `\"a\"`, `'plot'`, ..._";
+                readonly description: "_Recognize `\"a\"`, `'plot'`, ..._ In general, R allows to envelop names in quotations to allow for special characters such as spaces in variable names. However, this only works in the context of definitions. To access these names as variables, one has to either use function such as `get` or escape the name with backticks.";
+                readonly url: [{
+                    readonly name: string;
+                    readonly href: "https://adv-r.hadley.nz/names-values.html#non-syntactic";
+                }];
             }, {
                 readonly name: "Escaped";
                 readonly id: "name-escaped";
                 readonly supported: "fully";
                 readonly description: "_Recognize `` `a` ``, `` `plot` ``, ..._";
+                readonly url: [{
+                    readonly name: string;
+                    readonly href: "https://adv-r.hadley.nz/names-values.html#non-syntactic";
+                }];
+            }, {
+                readonly name: "Created";
+                readonly id: "name-created";
+                readonly supported: "partially";
+                readonly description: "_Recognize functions which resolve strings as identifiers, such as `get`, ..._";
+                readonly url: [{
+                    readonly name: "flowr#633";
+                    readonly href: string;
+                }];
             }];
         }, {
             readonly name: "Resolution";
@@ -538,25 +564,40 @@ export declare const flowrCapabilities: {
             readonly capabilities: readonly [{
                 readonly name: "S3";
                 readonly id: "oop-s3";
-                readonly note: "https://adv-r.hadley.nz/s3.html";
+                readonly url: [{
+                    readonly name: string;
+                    readonly href: "https://adv-r.hadley.nz/s3.html";
+                }];
                 readonly supported: "not";
                 readonly description: "_Handle S3 classes and methods as one unit (with attributes etc.). Including Dispatch and Inheritance._ We do not support typing currently and do not handle objects of these classes \"as units.\"";
             }, {
                 readonly name: "S4";
                 readonly id: "oop-s4";
-                readonly note: "https://adv-r.hadley.nz/s4.html";
+                readonly url: [{
+                    readonly name: string;
+                    readonly href: "https://adv-r.hadley.nz/s4.html";
+                }];
                 readonly supported: "not";
                 readonly description: "_Handle S4 classes and methods as one unit. Including Dispatch and Inheritance_ We do not support typing currently and do not handle objects of these classes \"as units.\"";
             }, {
                 readonly name: "R6";
                 readonly id: "oop-r6";
-                readonly note: "https://adv-r.hadley.nz/r6.html";
+                readonly url: [{
+                    readonly name: string;
+                    readonly href: "https://adv-r.hadley.nz/r6.html";
+                }];
                 readonly supported: "not";
                 readonly description: "_Handle R6 classes and methods as one unit. Including Dispatch and Inheritance, as well as its Reference Semantics, Access Control, Finalizers, and Introspection._ We do not support typing currently and do not handle objects of these classes \"as units.\"";
             }, {
                 readonly name: "R7/S7";
                 readonly id: "r7-s7";
-                readonly note: "https://www.r-bloggers.com/2022/12/what-is-r7-a-new-oop-system-for-r/, https://cran.r-project.org/web/packages/S7/index.html";
+                readonly url: [{
+                    readonly name: "R7";
+                    readonly href: "https://www.r-bloggers.com/2022/12/what-is-r7-a-new-oop-system-for-r/";
+                }, {
+                    readonly name: "S7";
+                    readonly href: "https://cran.r-project.org/web/packages/S7/index.html";
+                }];
                 readonly supported: "not";
                 readonly description: "_Handle R7 classes and methods as one unit. Including Dispatch and Inheritance, as well as its Reference Semantics, Validators, ..._ We do not support typing currently and do not handle objects of these classes \"as units.\"";
             }];

package/r-bridge/data/data.js

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

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

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