@eagleoutice/flowr 2.6.1 → 2.6.3

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

@@ -7,14 +7,10 @@ exports.mermaidHide = void 0;
 exports.getTypeScriptSourceFiles = getTypeScriptSourceFiles;
 exports.dropGenericsFromTypeName = dropGenericsFromTypeName;
 exports.removeCommentSymbolsFromTypeScriptComment = removeCommentSymbolsFromTypeScriptComment;
-exports.getTextualCommentsFromTypeScript = getTextualCommentsFromTypeScript;
 exports.getStartLineOfTypeScriptNode = getStartLineOfTypeScriptNode;
-exports.getType = getType;
-exports.followTypeReference = followTypeReference;
-exports.getTypePathForTypeScript = getTypePathForTypeScript;
 exports.getTypePathLink = getTypePathLink;
+exports.visualizeMermaidClassDiagram = visualizeMermaidClassDiagram;
 exports.getTypesFromFolder = getTypesFromFolder;
-exports.implSnippet = implSnippet;
 exports.printHierarchy = printHierarchy;
 exports.printCodeOfElement = printCodeOfElement;
 exports.shortLink = shortLink;
@@ -30,19 +26,36 @@ const doc_code_1 = require("./doc-code");
 const doc_structure_1 = require("./doc-structure");
 const html_hover_over_1 = require("../../util/html-hover-over");
 const doc_general_1 = require("./doc-general");
+const options = {
+    target: typescript_1.default.ScriptTarget.ESNext,
+    skipLibCheck: true,
+    skipDefaultLibCheck: true,
+    allowJs: true,
+    strict: false,
+    checkJs: false,
+    strictNullChecks: false,
+    noUncheckedIndexedAccess: false,
+    noUncheckedSideEffectImports: false,
+    noCheck: true,
+    noEmit: true,
+    noResolve: true,
+    noUnusedLocals: false,
+    alwaysStrict: true,
+    incremental: false,
+    types: [],
+    lib: [],
+    noLib: true,
+    moduleResolution: typescript_1.default.ModuleResolutionKind.Classic,
+    allowUnreachableCode: true,
+    allowUnusedLabels: true,
+    disableSolutionSearching: true,
+};
+/**
+ * Retrieve TypeScript source files from the given file names.
+ */
 function getTypeScriptSourceFiles(fileNames) {
     try {
-        const program = typescript_1.default.createProgram(fileNames, {
-            target: typescript_1.default.ScriptTarget.ESNext,
-            skipLibCheck: true,
-            skipDefaultLibCheck: true,
-            allowJs: true,
-            checkJs: false,
-            strictNullChecks: false,
-            noUncheckedIndexedAccess: false,
-            noUncheckedSideEffectImports: false,
-            noCheck: true
-        });
+        const program = typescript_1.default.createProgram(fileNames, options);
         return { program, files: fileNames.map(fileName => program.getSourceFile(fileName)).filter(file => !!file) };
     }
     catch (err) {
@@ -50,20 +63,47 @@ function getTypeScriptSourceFiles(fileNames) {
         return { files: [], program: undefined };
     }
 }
+const DropGenericsPattern = /<.*>/g;
+/**
+ * Drop generics from a TypeScript type name.
+ * @example
+ * ```ts
+ * const typeName = 'MyType<T, U>';
+ * const cleanName = dropGenericsFromTypeName(typeName);
+ * console.log(cleanName); // 'MyType'
+ * ```
+ */
 function dropGenericsFromTypeName(type) {
     let previous;
     do {
         previous = type;
-        type = type.replace(/<.*>/g, '');
+        type = type.replace(DropGenericsPattern, '');
     } while (type !== previous);
     return type;
 }
+const PruneDocCommentPattern = /^\/\*\*?|\*\/$|^\s*\*\s?|\s*\*$/gm;
+const PrunedocLinkPattern = /\{@[a-zA-Z]+ ([^}]+\|)?(?<name>[^}]+)}/gm;
+/**
+ * Remove comment symbols from a TypeScript comment string.
+ * This also takes care of special JSDoc tags like `{@link ...}` and `{@see ...}`.
+ * @example
+ * ```ts
+ * const comment = '/**\n* This is a comment.\n* It has multiple lines.\n *\/'; // closing comment sadly escaped for ts doc
+ * const cleaned = removeCommentSymbolsFromTypeScriptComment(comment);
+ * console.log(cleaned);
+ * ```
+ * This will output:
+ * ```md
+ * This is a comment.
+ * It has multiple lines.
+ * ```
+ */
 function removeCommentSymbolsFromTypeScriptComment(comment) {
     return comment
         // remove '/** \n * \n */...
-        .replace(/^\/\*\*?/gm, '').replace(/^\s*\*\s*/gm, '').replace(/\*\/$/gm, '').replace(/^\s*\*/gm, '')
-        /* replace {@key foo|bar} with `bar` and {@key foo} with `foo` */
-        .replace(/\{@[a-zA-Z]+ ([^}]+\|)?(?<name>[^}]+)}/gm, '<code>$<name></code>')
+        .replace(PruneDocCommentPattern, '')
+        // replace {@key foo|bar} with `bar` and {@key foo} with `foo`
+        .replace(PrunedocLinkPattern, '<code>$<name></code>')
         .trim();
 }
 function getTextualCommentsFromTypeScript(node) {
@@ -81,6 +121,9 @@ function getTextualCommentsFromTypeScript(node) {
     }
     return out;
 }
+/**
+ *
+ */
 function getStartLineOfTypeScriptNode(node, sourceFile) {
     const lineStart = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line;
     return lineStart + 1;
@@ -115,7 +158,7 @@ function collectHierarchyInformation(sourceFiles, options) {
             const baseTypes = node.heritageClauses?.flatMap(clause => clause.types
                 .map(type => type.getText(sourceFile) ?? '')
                 .map(dropGenericsFromTypeName)) ?? [];
-            const generics = node.typeParameters?.map(param => param.getText(sourceFile) ?? '') || [];
+            const generics = node.typeParameters?.map(param => param.getText(sourceFile) ?? '') ?? [];
             hierarchyList.push({
                 name: dropGenericsFromTypeName(interfaceName),
                 node,
@@ -141,7 +184,7 @@ function collectHierarchyInformation(sourceFiles, options) {
                     .map(dropGenericsFromTypeName);
             }
             else if (typescript_1.default.isTypeReferenceNode(node.type)) {
-                baseTypes = [...followTypeReference(node.type, sourceFile)].map(dropGenericsFromTypeName);
+                baseTypes = followTypeReference(node.type, sourceFile).map(dropGenericsFromTypeName);
             }
             const generics = node.typeParameters?.map(param => param.getText(sourceFile) ?? '') ?? [];
             hierarchyList.push({
@@ -245,14 +288,18 @@ function collectHierarchyInformation(sourceFiles, options) {
         }
         typescript_1.default.forEachChild(node, child => visit(child, sourceFile));
     };
-    sourceFiles.forEach(sourceFile => {
-        visit(sourceFile, sourceFile);
-    });
+    for (const sf of sourceFiles) {
+        visit(sf, sf);
+    }
     return hierarchyList;
 }
 function getTypePathForTypeScript({ filePath }) {
     return filePath.replace(/^.*\/src\//, 'src/').replace(/^.*\/test\//, 'test/');
 }
+/**
+ * Return the link to the type in the source code.
+ * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
+ */
 function getTypePathLink(elem, prefix = doc_files_1.RemoteFlowrFilePathBaseRef) {
     const fromSource = getTypePathForTypeScript(elem);
     return `${prefix}/${fromSource}#L${elem.lineNumber}`;
@@ -308,6 +355,9 @@ function generateMermaidClassDiagram(hierarchyList, rootName, options, visited =
     }
     return collect;
 }
+/**
+ * Visualize the type hierarchy as a mermaid class diagram.
+ */
 function visualizeMermaidClassDiagram(hierarchyList, options) {
     if (!options.typeNameForMermaid) {
         return undefined;
@@ -336,18 +386,24 @@ function getTypesFromFileAsMermaid(fileNames, options) {
  */
 function getTypesFromFolder(options) {
     (0, assert_1.guard)(options.rootFolder !== undefined || options.files !== undefined, 'Either rootFolder or files must be provided');
-    const files = [...options.files ?? []];
+    let files = [...options.files ?? []];
     if (options.rootFolder) {
-        for (const fileBuff of fs_1.default.readdirSync(options.rootFolder, { recursive: true })) {
-            const file = fileBuff.toString();
-            if (file.endsWith('.ts')) {
-                files.push(path_1.default.join(options.rootFolder, file));
-            }
+        const folders = Array.isArray(options.rootFolder) ? options.rootFolder : [options.rootFolder];
+        for (const folder of folders) {
+            files = files.concat(fs_1.default.readdirSync(folder, { recursive: true })
+                .filter(f => {
+                const p = f.toString();
+                return p.endsWith('.ts')
+                    && !p.endsWith('.test.ts')
+                    && !p.endsWith('-app.ts')
+                    && !p.endsWith('.d.ts');
+            })
+                .map(f => path_1.default.join(folder, f.toString())));
         }
     }
     return getTypesFromFileAsMermaid(files, options);
 }
-function implSnippet(node, program, showName = true, nesting = 0, open = false) {
+function implSnippet(node, program, showName = true, nesting = 0, open = false, showImplSnippet = true) {
     (0, assert_1.guard)(node !== undefined, 'Node must be defined => invalid change of type name?');
     const indent = ' '.repeat(nesting * 2);
     const bold = node.kind === 'interface' || node.kind === 'enum' ? '**' : '';
@@ -356,13 +412,22 @@ function implSnippet(node, program, showName = true, nesting = 0, open = false)
     if (text.trim() !== '') {
         text = '  ' + text;
     }
-    const code = node.node.getFullText(program.getSourceFile(node.node.getSourceFile().fileName));
-    text += `\n<details${open ? ' open' : ''}><summary style="color:gray">Defined at <a href="${getTypePathLink(node)}">${getTypePathLink(node, '.')}</a></summary>\n\n${(0, doc_code_1.codeBlock)('ts', code)}\n\n</details>\n`;
+    if (showImplSnippet) {
+        const code = node.node.getFullText(program.getSourceFile(node.node.getSourceFile().fileName));
+        text += `\n<details${open ? ' open' : ''}><summary style="color:gray">Defined at <a href="${getTypePathLink(node)}">${getTypePathLink(node, '.')}</a></summary>\n\n${(0, doc_code_1.codeBlock)('ts', code)}\n\n</details>\n`;
+    }
+    else {
+        text += `\n<br/><i>(Defined at <a href="${getTypePathLink(node)}">${getTypePathLink(node, '.')}</a>)</i>\n`;
+    }
     const init = showName ? `* ${bold}[${node.name}](${getTypePathLink(node)})${bold} ${sep}${indent}` : '';
     return ` ${indent}${showName ? init : ''} ${text.replaceAll('\t', '    ').split(/\n/g).join(`\n${indent}   `)}`;
 }
 exports.mermaidHide = ['Leaf', 'Location', 'Namespace', 'Base', 'WithChildren', 'Partial', 'RAccessBase'];
-function printHierarchy({ program, info, root, collapseFromNesting = 1, initialNesting = 0, maxDepth = 20, openTop }) {
+/**
+ * Print the hierarchy of types starting from the given root.
+ * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
+ */
+function printHierarchy({ program, info, root, collapseFromNesting = 1, initialNesting = 0, maxDepth = 20, openTop, showImplSnippet = true }) {
     if (initialNesting > maxDepth) {
         return '';
     }
@@ -370,13 +435,13 @@ function printHierarchy({ program, info, root, collapseFromNesting = 1, initialN
     if (!node) {
         return '';
     }
-    const thisLine = implSnippet(node, program, true, initialNesting, initialNesting === 0 && openTop);
+    const thisLine = implSnippet(node, program, true, initialNesting, initialNesting === 0 && openTop, showImplSnippet);
     const result = [];
     for (const baseType of node.extends) {
         if (exports.mermaidHide.includes(baseType)) {
             continue;
         }
-        const res = printHierarchy({ program, info: info, root: baseType, collapseFromNesting, initialNesting: initialNesting + 1, maxDepth });
+        const res = printHierarchy({ program, info: info, root: baseType, collapseFromNesting, initialNesting: initialNesting + 1, maxDepth, showImplSnippet });
         result.push(res);
     }
     const out = result.join('\n');
@@ -387,6 +452,12 @@ function printHierarchy({ program, info, root, collapseFromNesting = 1, initialN
         return thisLine + (out ? '\n' + out : '');
     }
 }
+/**
+ * Print an element from the info as code block.
+ * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
+ *
+ * This is great to show examples that are directly taken from the source code.
+ */
 function printCodeOfElement({ program, info, dropLinesEnd = 0, dropLinesStart = 0, doNotAutoGobble, hideDefinedAt }, name) {
     const node = info.find(e => e.name === name);
     if (!node) {
@@ -451,7 +522,8 @@ function retrieveNode(name, hierarchy, fuzzy = false, type = undefined) {
     return [container, name, node[0]];
 }
 /**
- * Create a short link to a type in the documentation
+ * Create a short link to a type in the documentation.
+ * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
  * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
  *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
  * @param hierarchy - The hierarchy of types to search in
@@ -471,8 +543,16 @@ function shortLink(name, hierarchy, codeStyle = true, realNameWrapper = 'b') {
     }
     const comments = node.comments?.join('\n').replace(/\\?\n|```[a-zA-Z]*|\s\s*/g, ' ').replace(/<\/?code>|`/g, '').replace(/<\/?p\/?>/g, ' ').replace(/"/g, '\'') ?? '';
     return `<a href="${getTypePathLink(node)}">${codeStyle ? '<code>' : ''}${(node.comments?.length ?? 0) > 0 ?
-        (0, html_hover_over_1.textWithTooltip)(pkg ? `${pkg}::<${realNameWrapper}>${mainName}</${realNameWrapper}>` : mainName, comments.length > 400 ? comments.slice(0, 400) + '...' : comments) : node.name}${codeStyle ? '</code>' : ''}</a>`;
+        (0, html_hover_over_1.textWithTooltip)(pkg ? `${pkg}::<${realNameWrapper}>${mainName}</${realNameWrapper}>` : mainName, comments.length > 400 ? comments.slice(0, 400) + '...' : comments) :
+        pkg ? `${pkg}::<${realNameWrapper}>${mainName}</${realNameWrapper}>` : mainName}${codeStyle ? '</code>' : ''}</a>`;
 }
+/**
+ * Create a short link to a type in the documentation.
+ * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
+ * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
+ *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
+ * @param hierarchy - The hierarchy of types to search in
+ */
 function shortLinkFile(name, hierarchy) {
     const res = retrieveNode(name, hierarchy);
     if (!res) {
@@ -482,6 +562,15 @@ function shortLinkFile(name, hierarchy) {
     const [, , node] = res;
     return `<a href="${getTypePathLink(node)}">${getTypePathForTypeScript(node)}</a>`;
 }
+/**
+ * Retrieve documentation comments for a type.
+ * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
+ * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
+ *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
+ * @param hierarchy - The hierarchy of types to search in
+ * @param prefix    - A prefix to add to each line of the documentation
+ * @param filter    - Optional filters for retrieving the documentation
+ */
 function getDocumentationForType(name, hierarchy, prefix = '', filter) {
     const res = retrieveNode(name, hierarchy, filter?.fuzzy, filter?.type);
     if (!res) {

package/documentation/index.d.ts

@@ -1,9 +1,9 @@
-export * from './print-core-wiki';
-export * from './print-query-wiki';
-export * from './print-search-wiki';
-export * from './print-engines-wiki';
-export * from './print-interface-wiki';
-export * from './print-dataflow-graph-wiki';
-export * from './print-normalized-ast-wiki';
-export * from './print-capabilities-markdown';
-export * from './print-linting-and-testing-wiki';
+export * from './wiki-core';
+export * from './wiki-query';
+export * from './wiki-search';
+export * from './wiki-engine';
+export * from './wiki-interface';
+export * from './wiki-dataflow-graph';
+export * from './wiki-normalized-ast';
+export * from './doc-capabilities';
+export * from './wiki-linting-and-testing';

package/documentation/index.js

@@ -14,13 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./print-core-wiki"), exports);
-__exportStar(require("./print-query-wiki"), exports);
-__exportStar(require("./print-search-wiki"), exports);
-__exportStar(require("./print-engines-wiki"), exports);
-__exportStar(require("./print-interface-wiki"), exports);
-__exportStar(require("./print-dataflow-graph-wiki"), exports);
-__exportStar(require("./print-normalized-ast-wiki"), exports);
-__exportStar(require("./print-capabilities-markdown"), exports);
-__exportStar(require("./print-linting-and-testing-wiki"), exports);
+__exportStar(require("./wiki-core"), exports);
+__exportStar(require("./wiki-query"), exports);
+__exportStar(require("./wiki-search"), exports);
+__exportStar(require("./wiki-engine"), exports);
+__exportStar(require("./wiki-interface"), exports);
+__exportStar(require("./wiki-dataflow-graph"), exports);
+__exportStar(require("./wiki-normalized-ast"), exports);
+__exportStar(require("./doc-capabilities"), exports);
+__exportStar(require("./wiki-linting-and-testing"), exports);
 //# sourceMappingURL=index.js.map

package/documentation/issue-linting-rule.d.ts

@@ -0,0 +1,9 @@
+import type { DocMakerArgs } from './wiki-mk/doc-maker';
+import { DocMaker } from './wiki-mk/doc-maker';
+/**
+ * https://github.com/flowr-analysis/flowr/blob/main/.github/ISSUE_TEMPLATE/linting-rule.yaml
+ */
+export declare class IssueLintingRule extends DocMaker {
+    constructor();
+    text({ ctx }: DocMakerArgs): string;
+}

package/documentation/{print-linter-issue.js → issue-linting-rule.js}

@@ -1,15 +1,11 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const log_1 = require("../../test/functionality/_helper/log");
-const doc_types_1 = require("./doc-util/doc-types");
-const path_1 = __importDefault(require("path"));
+exports.IssueLintingRule = void 0;
 const linter_tags_1 = require("../linter/linter-tags");
 const doc_general_1 = require("./doc-util/doc-general");
 const doc_files_1 = require("./doc-util/doc-files");
 const linter_rules_1 = require("../linter/linter-rules");
+const doc_maker_1 = require("./wiki-mk/doc-maker");
 /* this prints the yaml configuration for the GitHub issue template to request a new linter rule / an update */
 function summarizeIfTooLong(text, maxLength = 52) {
     if (text.length <= maxLength) {
@@ -17,11 +13,15 @@ function summarizeIfTooLong(text, maxLength = 52) {
     }
     return text.slice(0, maxLength - 1) + '…';
 }
-function getText() {
-    const types = (0, doc_types_1.getTypesFromFolder)({
-        rootFolder: path_1.default.resolve('./src/linter/')
-    });
-    return `
+/**
+ * https://github.com/flowr-analysis/flowr/blob/main/.github/ISSUE_TEMPLATE/linting-rule.yaml
+ */
+class IssueLintingRule extends doc_maker_1.DocMaker {
+    constructor() {
+        super('.github/ISSUE_TEMPLATE/linting-rule.yaml', module.filename, '', false);
+    }
+    text({ ctx }) {
+        return `
 name: Linting Rule
 description: Suggest either a new linting rule or an improvement to an existing one. 
 title: "[Linter]: "
@@ -48,9 +48,9 @@ body:
       options:
         - New Rule
 ${(0, doc_general_1.prefixLines)(Object.keys(linter_rules_1.LintingRules).sort().map(name => {
-        const rule = linter_rules_1.LintingRules[name];
-        return `- ${rule.info.name}`;
-    }).join('\n'), '        ')}
+            const rule = linter_rules_1.LintingRules[name];
+            return `- ${rule.info.name}`;
+        }).join('\n'), '        ')}
       default: 0
   - type: checkboxes
     id: tags
@@ -59,13 +59,10 @@ ${(0, doc_general_1.prefixLines)(Object.keys(linter_rules_1.LintingRules).sort()
       description: Select any tags that you think apply to the linting rule you are suggesting. If you try to suggest a new linting rule, please only select those that you think apply after your suggestions.
       options:
 ${(0, doc_general_1.prefixLines)(Object.entries(linter_tags_1.LintingRuleTag).map(([name]) => {
-        return `- label: '**${name}**: ${summarizeIfTooLong((0, doc_types_1.getDocumentationForType)('LintingRuleTag::' + name, types.info).replaceAll(/\n/g, ' ').replaceAll('\'', '\\\'').trim())}'\n  required: false`;
-    }).join('\n'), '        ')}
-`.trim();
-}
-/** if we run this script, we want a Markdown representation of the capabilities */
-if (require.main === module) {
-    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
-    console.log(getText());
+            return `- label: '**${name}**: ${summarizeIfTooLong(ctx.doc('LintingRuleTag::' + name).replaceAll(/\n/g, ' ').replaceAll('\'', '\\\'').trim())}'\n  required: false`;
+        }).join('\n'), '        ')}
+	`.trim();
+    }
 }
-//# sourceMappingURL=print-linter-issue.js.map
+exports.IssueLintingRule = IssueLintingRule;
+//# sourceMappingURL=issue-linting-rule.js.map

package/documentation/wiki-analyzer.d.ts

@@ -0,0 +1,9 @@
+import type { DocMakerArgs } from './wiki-mk/doc-maker';
+import { DocMaker } from './wiki-mk/doc-maker';
+/**
+ * https://github.com/flowr-analysis/flowr/wiki/Analyzer
+ */
+export declare class WikiAnalyzer extends DocMaker {
+    constructor();
+    text({ ctx }: DocMakerArgs): string;
+}