@eagleoutice/flowr 2.8.2 → 2.8.4

package/r-bridge/roxygen2/documentation-provider.d.ts

@@ -0,0 +1,15 @@
+import type { AstIdMap, ParentInformation } from '../lang-4.x/ast/model/processing/decorate';
+import type { NodeId } from '../lang-4.x/ast/model/processing/node-id';
+import type { RoxygenTag } from './roxygen-ast';
+export interface DocumentationInfo {
+    doc?: Documentation;
+}
+export type Documentation = RoxygenTag | readonly RoxygenTag[];
+/**
+ * Given a normalized AST and a node ID, returns the Roxygen documentation (if any) associated with that node.
+ * Please note that this does more than {@link parseRoxygenCommentsOfNode}, as it also traverses up the AST to find documentation.
+ * Additionally, this function instruments the normalized AST to cache the parsed documentation for future queries.
+ * @param idMap   - The AST ID map to use for looking up nodes and traversing the AST.
+ * @param nodeId  - The ID of the node to get documentation for.
+ */
+export declare function getDocumentationOf(nodeId: NodeId, idMap: AstIdMap<ParentInformation & DocumentationInfo>): Documentation | undefined;

package/r-bridge/roxygen2/documentation-provider.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDocumentationOf = getDocumentationOf;
+const roxygen_ast_1 = require("./roxygen-ast");
+const type_1 = require("../lang-4.x/ast/model/type");
+const roxygen_parse_1 = require("./roxygen-parse");
+const CommentRetriever = {
+    [type_1.RType.Comment]: n => (0, roxygen_parse_1.parseRoxygenComment)([n.lexeme]),
+    [type_1.RType.Parameter]: (n, idMap) => {
+        // get the documentation of the parent function
+        const doc = n.info.parent ? getDocumentationOf(n.info.parent, idMap) : undefined;
+        const paramName = n.lexeme;
+        if (doc && paramName) {
+            if (Array.isArray(doc)) {
+                const res = doc.filter(t => t.type === roxygen_ast_1.KnownRoxygenTags.Param && t.value.name === paramName);
+                if (res.length === 1) {
+                    return res[0];
+                }
+                else {
+                    return res;
+                }
+            }
+            else {
+                if (doc.type === roxygen_ast_1.KnownRoxygenTags.Param && doc.value.name === paramName) {
+                    return doc;
+                }
+            }
+        }
+        return undefined;
+    }
+};
+/**
+ * Given a normalized AST and a node ID, returns the Roxygen documentation (if any) associated with that node.
+ * Please note that this does more than {@link parseRoxygenCommentsOfNode}, as it also traverses up the AST to find documentation.
+ * Additionally, this function instruments the normalized AST to cache the parsed documentation for future queries.
+ * @param idMap   - The AST ID map to use for looking up nodes and traversing the AST.
+ * @param nodeId  - The ID of the node to get documentation for.
+ */
+function getDocumentationOf(nodeId, idMap) {
+    const node = idMap.get(nodeId);
+    if (!node) {
+        return undefined;
+    }
+    else if ('doc' in node.info) {
+        return node.info.doc;
+    }
+    const retriever = CommentRetriever[node.type] ?? ((c, a) => (0, roxygen_parse_1.parseRoxygenCommentsOfNode)(c, a)?.tags);
+    const doc = retriever(node, idMap);
+    if (doc) {
+        // to avoid endless recursion, we block the caching here once:
+        node.info.doc = undefined;
+        // cache the documentation for future queries
+        const expanded = expandInheritsOfTags(doc, idMap);
+        node.info.doc = expanded;
+        return expanded;
+    }
+    return doc;
+}
+function expandInheritsOfTags(tags, idMap) {
+    const expandedTags = [];
+    const tagArray = Array.isArray(tags) ? tags : [tags];
+    for (const tag of tagArray) {
+        const expanded = expandInheritOfTag(tag, tagArray, idMap);
+        if (!expanded) {
+            continue;
+        }
+        if (Array.isArray(expanded)) {
+            expandedTags.push(...expanded);
+        }
+        else {
+            expandedTags.push(expanded);
+        }
+    }
+    if (expandedTags.length === 1) {
+        return expandedTags[0];
+    }
+    return expandedTags;
+}
+function getDocumentationOfByName(name, idMap) {
+    for (const [, node] of idMap) {
+        const nodeName = node.lexeme ?? node.info.fullLexeme;
+        if (nodeName !== name) {
+            continue;
+        }
+        return getDocumentationOf(node.info.id, idMap);
+    }
+}
+function filterDocumentationForParams(doc, filter) {
+    if (!doc) {
+        return doc;
+    }
+    if (Array.isArray(doc)) {
+        return doc.filter(filter);
+    }
+    else {
+        return filter(doc) ? doc : undefined;
+    }
+}
+function expandInheritOfTag(tag, otherTags, idMap) {
+    if (tag.type === roxygen_ast_1.KnownRoxygenTags.Inherit) {
+        const inheritDoc = getDocumentationOfByName(tag.value.source, idMap);
+        return filterDocumentationForParams(inheritDoc, t => tag.value.components.includes(t.type));
+    }
+    else if (tag.type === roxygen_ast_1.KnownRoxygenTags.InheritDotParams) {
+        const inheritDoc = getDocumentationOfByName(tag.value.source, idMap);
+        return filterDocumentationForParams(inheritDoc, t => t.type === roxygen_ast_1.KnownRoxygenTags.Param && t.value.name === '...');
+    }
+    else if (tag.type === roxygen_ast_1.KnownRoxygenTags.InheritParams) {
+        const inheritDoc = getDocumentationOfByName(tag.value, idMap);
+        const alreadyExplainedParams = new Set(otherTags.filter(t => t.type === roxygen_ast_1.KnownRoxygenTags.Param).map(t => t.value.name));
+        return filterDocumentationForParams(inheritDoc, t => t.type === roxygen_ast_1.KnownRoxygenTags.Param && !alreadyExplainedParams.has(t.value.name));
+    }
+    return tag;
+}
+//# sourceMappingURL=documentation-provider.js.map

package/r-bridge/roxygen2/roxygen-parse.d.ts

@@ -4,6 +4,8 @@ import type { AstIdMap, ParentInformation } from '../lang-4.x/ast/model/processi
 /**
  * Parses the roxygen comments attached to a node into a RoxygenBlock AST node.
  * Will return `undefined` if there are no valid roxygen comments attached to the node.
+ * Please note that this does *not* do any clever mapping of parameters or requests.
+ * For a higher-level function that also traverses up the AST to find comments attached to parent nodes, see {@link getDocumentationOf}.
  * @param node  - The node to parse the roxygen comments for
  * @param idMap - An optional id map to traverse up the AST to find comments attached to parent nodes
  */
@@ -20,5 +22,5 @@ type TagLine = [tag: string, remTagLine?: string];
  * @see {@link parseRoxygenCommentsOfNode} - to parse comments attached to a node
  */
 export declare function parseRoxygenComment(commentText: readonly string[]): RoxygenTag[];
-export declare const firstAndRest: (firstName: string, secondName: string) => (s: RoxygenParseContext, t: TagLine) => void;
+export declare const firstAndRest: (firstName: string, secondName: string) => (s: RoxygenParseContext, t: TagLine) => TagLine | undefined;
 export {};

package/r-bridge/roxygen2/roxygen-parse.js

@@ -26,6 +26,8 @@ function prepareCommentContext(commentText) {
 /**
  * Parses the roxygen comments attached to a node into a RoxygenBlock AST node.
  * Will return `undefined` if there are no valid roxygen comments attached to the node.
+ * Please note that this does *not* do any clever mapping of parameters or requests.
+ * For a higher-level function that also traverses up the AST to find comments attached to parent nodes, see {@link getDocumentationOf}.
  * @param node  - The node to parse the roxygen comments for
  * @param idMap - An optional id map to traverse up the AST to find comments attached to parent nodes
  */
@@ -47,7 +49,7 @@ function parseRoxygenCommentsOfNode(node, idMap) {
         attachedTo: cur?.info.id,
         requestNode: node.info.id,
         range: [
-            ...(0, range_1.mergeRanges)(...comments.map(c => c.location)),
+            ...(0, range_1.mergeRanges)(comments.map(c => c.location)),
             comments.find(c => c.info.file)?.info.file
         ]
     };
@@ -64,7 +66,10 @@ function parseRoxygenComment(commentText) {
         tags: [],
         idx: 0
     };
-    val(state, [roxygen_ast_1.KnownRoxygenTags.Text]);
+    let tag = val(state, [roxygen_ast_1.KnownRoxygenTags.Text]);
+    while (tag) {
+        tag = parseRoxygenTag(state, tag);
+    }
     return state.tags;
 }
 function atEnd(state) {
@@ -123,7 +128,7 @@ function val(state, tagName, lineToVal = l => l.join('\n').trim()) {
             });
         }
     }
-    parseRoxygenTag(state, nextTag);
+    return nextTag;
 }
 const spaceVals = (s, t) => val(s, t, l => (0, args_1.splitAtEscapeSensitive)(l.join(' ')));
 const flagVal = (s, t) => val(s, t, () => undefined);
@@ -204,11 +209,12 @@ const TagMap = {
         content: l.join(' ')
     }))
 };
+/** returns the next tag */
 function parseRoxygenTag(state, tagName) {
     if (tagName === undefined) {
-        return;
+        return undefined;
     }
     const parser = TagMap[tagName[0]] ?? val;
-    parser(state, tagName);
+    return parser(state, tagName);
 }
 //# sourceMappingURL=roxygen-parse.js.map

package/util/r-version.js

@@ -9,6 +9,18 @@ function makeVersion(version, original) {
     semver.str = original;
     return semver;
 }
+function tryNormalizeNumberPart(part) {
+    try {
+        const res = Number(part);
+        if (!Number.isNaN(res)) {
+            return String(res);
+        }
+    }
+    catch {
+        return part;
+    }
+    return part;
+}
 function normalizeVersion(version) {
     version = version.trim();
     let comparator = '';
@@ -29,7 +41,11 @@ function normalizeVersion(version) {
             mainVersionParts.push('0');
         }
     }
-    return comparator + mainVersionParts.map(n => String(Number(n))).join('.') + (preReleaseParts.length > 0 ? `-${preReleaseParts.join('-')}` : '');
+    let prerelease = '';
+    if (preReleaseParts.length > 0) {
+        prerelease = '-' + preReleaseParts.join('-').split('.').map(part => tryNormalizeNumberPart(part)).join('.');
+    }
+    return comparator + mainVersionParts.map(tryNormalizeNumberPart).join('.') + prerelease;
 }
 const AnyVerWithMaybeRangeRegex = /(\s*[<>=~^]*\s*\d+(\.\d*)*(-[0-9A-Za-z-.]+)?)/g;
 function normalizeVersions(versions) {

package/util/range.d.ts

@@ -52,7 +52,7 @@ export declare function invalidRange(): SourceRange;
  * If you are interested in combining overlapping ranges into a minimal set of ranges, see {@link combineRanges}.
  * @throws if no ranges are provided
  */
-export declare function mergeRanges(...rs: (SourceRange | undefined)[]): SourceRange;
+export declare function mergeRanges(rs?: (SourceRange | undefined)[]): SourceRange;
 /**
  * @returns true iff `r1` starts and ends before `r2` starts (i.e., if `r1` and `r2` do not overlap and `r1` comes before `r2`
  */

package/util/range.js

@@ -45,7 +45,7 @@ function invalidRange() {
  * If you are interested in combining overlapping ranges into a minimal set of ranges, see {@link combineRanges}.
  * @throws if no ranges are provided
  */
-function mergeRanges(...rs) {
+function mergeRanges(rs = []) {
     const rsSafe = rs.filter(assert_1.isNotUndefined);
     (0, assert_1.guard)(rsSafe.length > 0, 'Cannot merge no ranges');
     return rsSafe.reduce(([sl, sc, el, ec], [nsl, nsc, nel, nec]) => [

package/util/version.js

@@ -6,7 +6,7 @@ exports.printVersionInformation = printVersionInformation;
 const semver_1 = require("semver");
 const assert_1 = require("./assert");
 // this is automatically replaced with the current version by release-it
-const version = '2.8.2';
+const version = '2.8.4';
 /**
  * Retrieves the current flowR version as a new {@link SemVer} object.
  */