@eagleoutice/flowr 2.6.2 → 2.7.0

package/documentation/{print-linter-wiki.js → wiki-linter.js}

@@ -3,12 +3,11 @@ 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");
+exports.WikiLinter = void 0;
 const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
 const doc_files_1 = require("./doc-util/doc-files");
 const linter_rules_1 = require("../linter/linter-rules");
 const doc_code_1 = require("./doc-util/doc-code");
-const shell_1 = require("../r-bridge/shell");
 const doc_query_1 = require("./doc-util/doc-query");
 const doc_types_1 = require("./doc-util/doc-types");
 const path_1 = __importDefault(require("path"));
@@ -18,9 +17,9 @@ const linter_tags_1 = require("../linter/linter-tags");
 const html_hover_over_1 = require("../util/html-hover-over");
 const strings_1 = require("../util/text/strings");
 const assert_1 = require("../util/assert");
-const doc_print_1 = require("./doc-util/doc-print");
 const doc_functions_1 = require("./doc-util/doc-functions");
 const linter_format_1 = require("../linter/linter-format");
+const doc_maker_1 = require("./wiki-mk/doc-maker");
 const SpecialTagColors = {
     [linter_tags_1.LintingRuleTag.Bug]: 'red',
     [linter_tags_1.LintingRuleTag.Security]: 'orange',
@@ -31,6 +30,11 @@ function makeTagBadge(name, info) {
     const doc = (0, doc_types_1.getDocumentationForType)('LintingRuleTag::' + name, info, '', { fuzzy: true }).replaceAll('\n', ' ');
     return (0, html_hover_over_1.textWithTooltip)(`<a href='#${name}'>![` + name + '](https://img.shields.io/badge/' + name.toLowerCase() + `-${SpecialTagColors[name] ?? 'teal'}) </a>`, doc);
 }
+function getPageNameForLintingRule(name) {
+    // convert file-path-validity to 'Linting Rule: File Path Validity'
+    const words = name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1));
+    return '[Linting Rule] ' + words.join(' ');
+}
 function prettyPrintExpectedOutput(expected) {
     if (expected.trim() === '[]') {
         return '* no lints';
@@ -50,7 +54,7 @@ function prettyPrintExpectedOutput(expected) {
         return line.replace(new RegExp('^' + indentation, 'g'), '');
     }).join('\n');
 }
-function buildSamplesFromLinterTestCases(shell, testFile) {
+function buildSamplesFromLinterTestCases(_parser, testFile) {
     const reports = (0, doc_functions_1.getFunctionsFromFolder)({ files: [path_1.default.resolve('test/functionality/linter/' + testFile)], fname: /assertLinter/ });
     if (reports.info.length === 0) {
         return '';
@@ -85,40 +89,40 @@ See [here](${(0, doc_types_1.getTypePathLink)({ filePath: report.source.fileName
     }
     return result;
 }
-function registerRules(rVersion, shell, tagTypes, format = 'short') {
+function registerRules(knownParser, tagTypes, format = 'short') {
     const ruleExplanations = new Map();
-    rule(shell, 'deprecated-functions', 'FunctionsToDetectConfig', 'DEPRECATED_FUNCTIONS', 'lint-deprecated-functions', `
+    rule(knownParser, 'deprecated-functions', 'FunctionsToDetectConfig', 'DEPRECATED_FUNCTIONS', 'lint-deprecated-functions', `
 first <- data.frame(x = c(1, 2, 3), y = c(1, 2, 3))
 second <- data.frame(x = c(1, 3, 2), y = c(1, 3, 2))
 dplyr::all_equal(first, second)
 `, tagTypes);
-    rule(shell, 'network-functions', 'NetworkFunctionsConfig', 'NETWORK_FUNCTIONS', 'lint-network-functions', `
+    rule(knownParser, 'network-functions', 'NetworkFunctionsConfig', 'NETWORK_FUNCTIONS', 'lint-network-functions', `
 read.csv("https://example.com/data.csv")
 download.file("https://foo.bar")
 `, tagTypes);
-    rule(shell, 'file-path-validity', 'FilePathValidityConfig', 'FILE_PATH_VALIDITY', 'lint-file-path-validity', `
+    rule(knownParser, 'file-path-validity', 'FilePathValidityConfig', 'FILE_PATH_VALIDITY', 'lint-file-path-validity', `
 my_data <- read.csv("C:/Users/me/Documents/My R Scripts/Reproducible.csv")
 `, tagTypes);
-    rule(shell, 'absolute-file-paths', 'AbsoluteFilePathConfig', 'ABSOLUTE_PATH', 'lint-absolute-path', `
+    rule(knownParser, 'absolute-file-paths', 'AbsoluteFilePathConfig', 'ABSOLUTE_PATH', 'lint-absolute-path', `
 read.csv("C:/Users/me/Documents/My R Scripts/Reproducible.csv")
 `, tagTypes);
-    rule(shell, 'unused-definitions', 'UnusedDefinitionConfig', 'UNUSED_DEFINITION', 'lint-unused-definition', `
+    rule(knownParser, 'unused-definitions', 'UnusedDefinitionConfig', 'UNUSED_DEFINITION', 'lint-unused-definition', `
 x <- 42
 y <- 3
 print(x)
 `, tagTypes);
-    rule(shell, 'seeded-randomness', 'SeededRandomnessConfig', 'SEEDED_RANDOMNESS', 'lint-seeded-randomness', 'runif(1)', tagTypes);
-    rule(shell, 'naming-convention', 'NamingConventionConfig', 'NAMING_CONVENTION', 'lint-naming-convention', `
+    rule(knownParser, 'seeded-randomness', 'SeededRandomnessConfig', 'SEEDED_RANDOMNESS', 'lint-seeded-randomness', 'runif(1)', tagTypes);
+    rule(knownParser, 'naming-convention', 'NamingConventionConfig', 'NAMING_CONVENTION', 'lint-naming-convention', `
 myVar <- 42
 print(myVar)
 `, tagTypes);
-    rule(shell, 'dataframe-access-validation', 'DataFrameAccessValidationConfig', 'DATA_FRAME_ACCESS_VALIDATION', 'lint-dataframe-access-validation', `
+    rule(knownParser, 'dataframe-access-validation', 'DataFrameAccessValidationConfig', 'DATA_FRAME_ACCESS_VALIDATION', 'lint-dataframe-access-validation', `
 df <- data.frame(id = 1:5, name = 6:10)
 df[6, "value"]
 `, tagTypes);
-    rule(shell, 'dead-code', 'DeadCodeConfig', 'DEAD_CODE', 'lint-dead-code', 'if(TRUE) 1 else 2', tagTypes);
-    rule(shell, 'useless-loop', 'UselessLoopConfig', 'USELESS_LOOP', 'lint-useless-loop', 'for(i in c(1)) { print(i) }', tagTypes);
-    function rule(shell, name, configType, ruleType, testfile, example, types) {
+    rule(knownParser, 'dead-code', 'DeadCodeConfig', 'DEAD_CODE', 'lint-dead-code', 'if(TRUE) 1 else 2', tagTypes);
+    rule(knownParser, 'useless-loop', 'UselessLoopConfig', 'USELESS_LOOP', 'lint-useless-loop', 'for(i in c(1)) { print(i) }', tagTypes);
+    function rule(parser, name, configType, ruleType, testfile, example, types) {
         const rule = linter_rules_1.LintingRules[name];
         const tags = rule.info.tags.toSorted((a, b) => {
             // sort but specials first
@@ -140,7 +144,7 @@ df[6, "value"]
         const certaintyText = `\`${(0, html_hover_over_1.textWithTooltip)(rule.info.certainty, certaintyDoc)}\``;
         if (format === 'short') {
             ruleExplanations.set(name, () => Promise.resolve(`
-	**[${rule.info.name}](${doc_files_1.FlowrWikiBaseRef}/lint-${name}):** ${rule.info.description} [see ${(0, doc_types_1.shortLinkFile)(ruleType, types)}]\\
+	**[${rule.info.name}](${doc_files_1.FlowrWikiBaseRef}/${encodeURIComponent(getPageNameForLintingRule(name))}):** ${rule.info.description} [see ${(0, doc_types_1.shortLinkFile)(ruleType, types)}]\\
 	${tags}
 
 		`.trim()));
@@ -148,7 +152,7 @@ df[6, "value"]
         else {
             ruleExplanations.set(name, async () => `
 
-${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'linter', rVersion })}
+${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'linter' })}
 ${(0, doc_structure_1.section)(rule.info.name + `&emsp;<sup>[<a href="${doc_files_1.FlowrWikiBaseRef}/Linter">overview</a>]</sup>`, 2, name)}
 
 ${tags}
@@ -173,9 +177,9 @@ ${(0, doc_code_1.codeBlock)('r', example)}
 
 The linting query can be used to run this rule on the above example:
 
-${await (0, doc_query_1.showQuery)(shell, example, [{ type: 'linter', rules: [{ name, config: {} }] }], { collapseQuery: true })}
+${await (0, doc_query_1.showQuery)(parser, example, [{ type: 'linter', rules: [{ name, config: {} }] }], { collapseQuery: true })}
 
-${buildSamplesFromLinterTestCases(shell, `${testfile}.test.ts`)}
+${buildSamplesFromLinterTestCases(parser, `${testfile}.test.ts`)}
 
 		`.trim());
         }
@@ -189,19 +193,18 @@ function getAllLintingRulesWitCertainty(certainty) {
     return Object.entries(linter_rules_1.LintingRules).filter(([_, rule]) => rule.info.certainty === certainty).map(([name]) => name);
 }
 function linkToRule(name) {
-    return `[${name}](${doc_files_1.FlowrWikiBaseRef}/lint-${name})`;
+    return `[${name}](${doc_files_1.FlowrWikiBaseRef}/${encodeURIComponent(getPageNameForLintingRule(name).replaceAll(' ', '-'))})`;
 }
-async function getTextMainPage(shell, tagTypes, rVersion) {
-    const rules = registerRules(rVersion, shell, tagTypes.info);
-    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'linter', rVersion })}
-
+async function getTextMainPage(knownParser, tagTypes) {
+    const rules = registerRules(knownParser, tagTypes.info);
+    return `
 This page describes the flowR linter, which is a tool that utilizes flowR's dataflow analysis to find common issues in R scripts. The linter can currently be used through the linter [query](${doc_files_1.FlowrWikiBaseRef}/Query%20API).
 For example:
 
 ${await (async () => {
         const code = 'read.csv("/root/x.txt")';
-        const res = await (0, doc_query_1.showQuery)(shell, code, [{ type: 'linter' }], { showCode: false, collapseQuery: true, collapseResult: false });
-        return await (0, doc_repl_1.documentReplSession)(shell, [{
+        const res = await (0, doc_query_1.showQuery)(knownParser, code, [{ type: 'linter' }], { showCode: false, collapseQuery: true, collapseResult: false });
+        return await (0, doc_repl_1.documentReplSession)(knownParser, [{
                 command: `:query @linter ${JSON.stringify(code)}`,
                 description: `
 The linter will analyze the code and return any issues found.
@@ -256,42 +259,43 @@ ${Object.entries(linter_format_1.LintingResultCertainty).map(([name, certainty])
 
 `.trim();
 }
-async function getRulesPages(shell, tagTypes, rVersion) {
-    const rules = registerRules(rVersion, shell, tagTypes.info, 'long');
+async function getRulesPages(knownParser, tagTypes) {
+    const rules = registerRules(knownParser, tagTypes.info, 'long');
     const result = {};
     for (const [name, rule] of rules) {
-        const filepath = path_1.default.resolve('./wiki', `lint-${name}.md`);
+        const filepath = path_1.default.join('wiki', `${getPageNameForLintingRule(name)}.md`);
         result[filepath] = await rule();
     }
     return result;
 }
 /** Maps file-names to their content, the 'main' file is named 'main' */
-async function getTexts(shell) {
-    const rVersion = (await shell.usedRVersion())?.format() ?? 'unknown';
+async function getTexts(parser) {
     const tagTypes = (0, doc_types_1.getTypesFromFolder)({
         rootFolder: path_1.default.resolve('./src/linter/'),
         inlineTypes: doc_types_1.mermaidHide
     });
     return {
-        'main': await getTextMainPage(shell, tagTypes, rVersion),
-        ...await getRulesPages(shell, tagTypes, rVersion)
+        'main': await getTextMainPage(parser, tagTypes),
+        ...await getRulesPages(parser, tagTypes)
     };
 }
-/* As an intermediary solution to changing the wiki system, we make this script generate separate files for each linter rule using fixed paths */
-if (require.main === module) {
-    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
-    const shell = new shell_1.RShell();
-    void (getTexts(shell).then(data => {
-        console.log(data['main']);
-        for (const [file, content] of Object.entries(data)) {
+/**
+ * https://github.com/flowr-analysis/flowr/wiki/Linter
+ */
+class WikiLinter extends doc_maker_1.DocMaker {
+    constructor() {
+        super('wiki/Linter.md', module.filename, 'linter');
+    }
+    async text({ treeSitter }) {
+        const texts = await getTexts(treeSitter);
+        for (const [file, content] of Object.entries(texts)) {
             if (file === 'main') {
-                continue; // main is printed above
+                continue; // main is printed below
             }
-            const filepath = path_1.default.resolve('./wiki', file);
-            (0, doc_print_1.writeWikiTo)(content, filepath);
+            this.writeSubFile(file, content);
         }
-    }).finally(() => {
-        shell.close();
-    }));
+        return texts['main'];
+    }
 }
-//# sourceMappingURL=print-linter-wiki.js.map
+exports.WikiLinter = WikiLinter;
+//# sourceMappingURL=wiki-linter.js.map

package/documentation/wiki-linting-and-testing.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/Linting-and-Testing
+ */
+export declare class WikiLintingAndTesting extends DocMaker {
+    constructor();
+    protected text({ ctx }: DocMakerArgs): string;
+}

package/documentation/{print-linting-and-testing-wiki.js → wiki-linting-and-testing.js}

@@ -1,26 +1,21 @@
 "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 log_2 = require("../util/log");
+exports.WikiLintingAndTesting = void 0;
+const log_1 = require("../util/log");
 const doc_code_1 = require("./doc-util/doc-code");
 const doc_files_1 = require("./doc-util/doc-files");
 const doc_structure_1 = require("./doc-util/doc-structure");
-const doc_types_1 = require("./doc-util/doc-types");
-const path_1 = __importDefault(require("path"));
-const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
 const doc_cli_option_1 = require("./doc-util/doc-cli-option");
-function getText() {
-    const { info } = (0, doc_types_1.getTypesFromFolder)({
-        rootFolder: path_1.default.resolve('./test'),
-        files: [path_1.default.resolve('./src/dataflow/graph/dataflowgraph-builder.ts'), path_1.default.resolve('./src/util/log.ts'), path_1.default.resolve('./src/slicing/static/static-slicer.ts')],
-        typeNameForMermaid: 'parameter',
-        inlineTypes: doc_types_1.mermaidHide
-    });
-    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'linting and testing definitions' })}
-
+const doc_maker_1 = require("./wiki-mk/doc-maker");
+/**
+ * https://github.com/flowr-analysis/flowr/wiki/Linting-and-Testing
+ */
+class WikiLintingAndTesting extends doc_maker_1.DocMaker {
+    constructor() {
+        super('wiki/Linting and Testing.md', module.filename, 'linting and testing definitions');
+    }
+    text({ ctx }) {
+        return `
 For the latest code coverage information, see [codecov.io](${doc_files_1.FlowrCodecovRef}), 
 for the latest benchmark results, see the [benchmark results](${doc_files_1.FlowrSiteBaseRef}/wiki/stats/benchmark) wiki page.
 
@@ -92,13 +87,13 @@ This folder contains three special and important elements:
 - \`test-summary.ts\` which may produce a summary of the covered capabilities.
 
 ${(0, doc_structure_1.block)({
-        type: 'WARNING',
-        content: `
+            type: 'WARNING',
+            content: `
 We name all test files using the \`.test.ts\` suffix and try to run them in parallel.
-Whenever this is impossible (e.g., when using ${(0, doc_types_1.shortLink)('withShell', info)}), please use _\`describe.sequential\`_
+Whenever this is impossible (e.g., when using ${ctx.link('withShell')}), please use _\`describe.sequential\`_
 to disable parallel execution for the respective test (otherwise, such tests are flaky).
 `
-    })}
+        })}
 
 <a id='test-labels'></a>
 #### 🏷️ Test Labels
@@ -128,13 +123,13 @@ assertDataflow(label('simple variable', ['name-normal']), shell,
 	'x', emptyGraph().use('0', 'x')
 );
 `)}
-Have a look at ${(0, doc_types_1.shortLink)('assertDataflow', info)}, ${(0, doc_types_1.shortLink)('label', info)}, and ${(0, doc_types_1.shortLink)('emptyGraph', info)} for more information.
+Have a look at ${ctx.link('assertDataflow')}, ${ctx.link('label')}, and ${ctx.link('emptyGraph')} for more information.
 
 When writing dataflow tests, additional settings can be used to reduce the amount of graph data that needs to be pre-written. Notably:
 
-- ${(0, doc_types_1.shortLink)('expectIsSubgraph', info)} indicates that the expected graph is a subgraph, rather than the full graph that the test should generate. 
+- ${ctx.link('expectIsSubgraph')} indicates that the expected graph is a subgraph, rather than the full graph that the test should generate. 
   The test will then only check if the supplied graph is contained in the result graph, rather than an exact match.
-- ${(0, doc_types_1.shortLink)('resolveIdsAsCriterion', info)} indicates that the ids given in the expected (sub)graph should be resolved as [slicing criteria](${doc_files_1.FlowrWikiBaseRef}/Terminology#slicing-criterion) rather than actual ids. 
+- ${ctx.link('resolveIdsAsCriterion')} indicates that the ids given in the expected (sub)graph should be resolved as [slicing criteria](${doc_files_1.FlowrWikiBaseRef}/Terminology#slicing-criterion) rather than actual ids. 
   For example, passing \`12@a\` as an id in the expected (sub)graph will cause it to be resolved as the corresponding id.
 
 The following example shows both in use:
@@ -265,15 +260,13 @@ You can also set the \`Auto Attach Filter\` setting to automatically attach the
 ### Logging
 
 *flowR* uses a wrapper around [tslog](https://www.npmjs.com/package/tslog) using a class named
-${(0, doc_types_1.shortLink)(log_2.FlowrLogger.name, info)}. They obey to, for example, the ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'verbose')}
+${ctx.link(log_1.FlowrLogger)}. They obey to, for example, the ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'verbose')}
 option. Throughout *flowR*, we use the \`log\` object (or subloggers of it) for logging.
-To create your own logger, you can use ${(0, doc_types_1.shortLink)(log_2.FlowrLogger.name + '::' + (new log_2.FlowrLogger().getSubLogger.name), info, true, 'i')}.
-For example, check out the ${(0, doc_types_1.shortLink)('slicerLogger', info)} for the static slicer.
+To create your own logger, you can use ${ctx.linkM(log_1.FlowrLogger, 'getSubLogger', { codeFont: true, realNameWrapper: 'i' })}.
+For example, check out the ${ctx.link('slicerLogger')} for the static slicer.
 
 `;
+    }
 }
-if (require.main === module) {
-    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
-    console.log(getText());
-}
-//# sourceMappingURL=print-linting-and-testing-wiki.js.map
+exports.WikiLintingAndTesting = WikiLintingAndTesting;
+//# sourceMappingURL=wiki-linting-and-testing.js.map

package/documentation/wiki-mk/doc-context.d.ts

@@ -0,0 +1,186 @@
+import type { FnElementInfo, PrintHierarchyArguments, TypeElementKind } from '../doc-util/doc-types';
+import type { RShell } from '../../r-bridge/shell';
+/**
+ * Context available when generating documentation for a wiki in markdown format
+ */
+export interface ElementFilter {
+    /** In case names collide, you can use this to further distinguish between them */
+    readonly file?: RegExp;
+    /** In case names collide, you can use this to further distinguish between them, by specifying the kind you search for */
+    readonly type?: TypeElementKind;
+    /** Whether to use fuzzy matching for the element name */
+    readonly fuzzy?: boolean;
+}
+/**
+ * Formatting options for links to code elements
+ */
+export interface LinkFormat {
+    /**
+     * Whether to use md code font for the link text
+     */
+    codeFont?: boolean;
+    /**
+     * Wrapper for the real name (if specified), e.g., to italicize or bold it
+     */
+    realNameWrapper?: 'i' | 'b';
+}
+export type ElementId = string;
+export type ElementIdOrRef = ElementId | {
+    name: string;
+} | (new () => unknown);
+type NamedPrototype = {
+    prototype: {
+        constructor: {
+            name: string;
+        };
+    };
+};
+type ProtoKeys<T> = T extends {
+    prototype: infer P;
+} ? keyof P : never;
+/**
+ * Provides methods to generate links, code snippets, and documentation for code elements.
+ * These wrap around a collection of useful helpers originating from the doc utils.
+ * To create an instance, use {@link makeDocContextForTypes} (although if you are writing a wiki, you get such an instance).
+ */
+export interface GeneralDocContext {
+    /**
+     * Generate a hyperlink to a code element in the wiki.
+     * If you want to reference the member of a class, use `ClassName::MemberName` as element name.
+     * For ease of use, you can also call {@link GeneralDocContext#linkM|linkM} to create a link to a member.
+     * @param element - The element to create a link for, the name can be qualified with `::` to specify the class.
+     *                  This causes the link to be usually printed as `ClassName::ElementName`. If you want to avoid showing
+     *                  the class name, use `:::` as separator. Please note that for elements with a sensible (`.name`),
+     *                  you can also pass the function/constructor reference directly (e.g., `link(MyClass)`).
+     * @param fmt     - Formatting options for the link (see {@link LinkFormat})
+     * @param filter  - An optional filter to further specify the element to link to, in case multiple elements with the same name exist.
+     * @example
+     * ```ts
+     * link(registerPluginMaker.name)
+     * ```
+     *
+     * Creates a (markdown) link to the `registerPluginMaker` function in the code base
+     * and, if available, attaches the TS documentation as tooltip.
+     * By using the `.name`, the link text will be `registerPluginMaker` but respect, e.g., renaming refactorings done in the code base.
+     * @see {@link linkFile}  - to create a link using the file path as name.
+     * @see {@link shortLink} - for the underlying impl.
+     * @see {@link dropGenericsFromTypeName} - to clean up type names for display.
+     */
+    link(element: ElementIdOrRef, fmt?: LinkFormat, filter?: ElementFilter): string;
+    /**
+     * Generate a hyperlink to a member of a class in the wiki.
+     * This is a convenience method around {@link GeneralDocContext#link|link}.
+     * @example
+     * ```ts
+     * linkM(MyClass, 'myMethod')
+     * ```
+     *
+     * Creates a (markdown) link to the `myMethod` member of the `MyClass` class in the code base.
+     * @see {@link GeneralWikiContext#link|link} - for the underlying impl.
+     */
+    linkM<T extends NamedPrototype>(cls: T, element: ProtoKeys<T>, fmt?: LinkFormat & {
+        hideClass?: boolean;
+    }, filter?: ElementFilter): string;
+    /**
+     * Generate a hyperlink to a type/element definition in the code base which is displayed using the file path as name
+     * @param element - The element to create a link for, the name can be qualified with `::` to specify the class.
+     * @example
+     * ```ts
+     * linkFile(registerPluginMaker.name)
+     * ```
+     * Creates a (markdown) link to the `registerPluginMaker` function in the code base
+     * using the file path as link name.
+     * @see {@link GeneralWikiContext#link|link} - to create a link with a custom name/using the type name by default.
+     * @see {@link linkFile}  - for the underlying impl.
+     */
+    linkFile(element: ElementIdOrRef): string;
+    /**
+     * Returns the documentation for a code element as markdown string.
+     * If you want to, e.g., prefix all of these lines with indentation or `> ` for blockquotes,
+     * use {@link prefixLines}.
+     * @param element - The element to create documentation for, the name can be qualified with `::` to specify the class.
+     * @param filter  - An optional filter to further specify the element to get the documentation for, in case multiple elements with the same name exist.
+     * @example
+     * ```ts
+     * doc(exampleFn.name)
+     * ```
+     *
+     * Creates the documentation for the `exampleFn` function in the code base as markdown string.
+     * @see {@link getDocumentationForType} - for the underlying impl.
+     * @see {@link removeCommentSymbolsFromTypeScriptComment} - to clean up TS doc comments.
+     */
+    doc(element: ElementIdOrRef, filter?: Omit<ElementFilter, 'file'>): string;
+    /**
+     * Returns the code snippet for a code element as markdown string.
+     * @param element - The element to create a code snippet for, the name can be qualified with `::` to specify the class.
+     * @param fmt     - Formatting options for the code snippet (see {@link FnElementInfo})
+     * @param filter  - An optional filter to further specify the element to get the code for, in case multiple elements with the same name exist.
+     * @example
+     * ```ts
+     * code(exampleFn.name, { dropLinesStart: 1, dropLinesEnd: 2  })
+     * ```
+     *
+     * Creates a code snippet for the `exampleFn` function in the code base,
+     * dropping the first and last two lines of the function definition.
+     * If, for example, the function looks like this:
+     *
+     * ```ts
+     * function exampleFn(a: number, b: number): number {
+     *    // This is an example
+     *     const result = a + b;
+     *     return result;
+     * }
+     * ```
+     *
+     * The resulting code snippet will be (auto-gobbled by default):
+     *
+     * ```ts
+     * // This is an example
+     * const result = a + b;
+     * ```
+     * @see {@link printCodeOfElement} - for the underlying impl.
+     */
+    code(element: ElementIdOrRef, fmt?: Omit<FnElementInfo, 'info' | 'program'>, filter?: ElementFilter): string;
+    /**
+     * Returns the hierarchy (e.g., class inheritance) for a code element as markdown string,
+     * including their documentation and snippets.
+     * @param element - The element to create a hierarchy for, the name can be qualified with `::` to specify the class.
+     * @param fmt     - Formatting options for the hierarchy (see {@link PrintHierarchyArguments})
+     * @param filter  - An optional filter to further specify the element to get the hierarchy for, in case multiple elements with the same name exist.
+     * @example
+     * ```ts
+     * hierarchy(MyClass.name, { maxDepth: 2 })
+     * ```
+     *
+     * Creates the hierarchy for the `MyClass` class in the code base,
+     * including up to two levels of inheritance.
+     * @see {@link printHierarchy} - for the underlying impl.
+     */
+    hierarchy(element: ElementIdOrRef, fmt?: Omit<PrintHierarchyArguments, 'info' | 'program' | 'root'>, filter?: ElementFilter): string;
+    /**
+     * Generates an auto-generation header for the wiki page.
+     * @param filename - The name of the file being generated. Probably use `module.filename`.
+     * @param purpose - The purpose of the file, e.g., 'wiki context for types'.
+     */
+    header(filename: string, purpose: string): Promise<string>;
+    /**
+     * Generates a mermaid diagram for the given code element, returned as markdown string.
+     * @param element - The element to create a mermaid diagram for, the name can be qualified with `::` to specify the class.
+     * @param inlineTypes - Optional list of type names to inline in the mermaid diagram (instead of linking them out).
+     */
+    mermaid(element: ElementIdOrRef, inlineTypes?: string[]): string;
+}
+/**
+ * Creates a wiki context for generating documentation for code elements.
+ * This context provides methods to create links, code snippets, and documentation for code elements.
+ * @param shell       - An optional RShell instance to retrieve the R version for the auto-generation header.
+ * @param rootFolders - The root folder(s) of the code base to analyze. Defaults to flower's `src/` **and** `test/` folder.
+ * @example
+ * ```ts
+ * const ctx = makeContextForTypes();
+ * const linkToFn = ctx.link('myFunction');
+ * const fnDoc = ctx.doc('myFunction');
+ * ```
+ */
+export declare function makeDocContextForTypes(shell?: RShell, ...rootFolders: string[]): GeneralDocContext;
+export {};

package/documentation/wiki-mk/doc-context.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeDocContextForTypes = makeDocContextForTypes;
+const doc_types_1 = require("../doc-util/doc-types");
+const path_1 = __importDefault(require("path"));
+const assert_1 = require("../../util/assert");
+const doc_auto_gen_1 = require("../doc-util/doc-auto-gen");
+function getNameFromElementIdOrRef(element) {
+    if (typeof element === 'function') {
+        return element.name;
+    }
+    else if (typeof element === 'object' && 'name' in element) {
+        return element.name;
+    }
+    else {
+        return element;
+    }
+}
+/**
+ * Creates a wiki context for generating documentation for code elements.
+ * This context provides methods to create links, code snippets, and documentation for code elements.
+ * @param shell       - An optional RShell instance to retrieve the R version for the auto-generation header.
+ * @param rootFolders - The root folder(s) of the code base to analyze. Defaults to flower's `src/` **and** `test/` folder.
+ * @example
+ * ```ts
+ * const ctx = makeContextForTypes();
+ * const linkToFn = ctx.link('myFunction');
+ * const fnDoc = ctx.doc('myFunction');
+ * ```
+ */
+function makeDocContextForTypes(shell, ...rootFolders) {
+    if (rootFolders.length === 0) {
+        rootFolders.push(path_1.default.resolve(__dirname, '../../../src'));
+        rootFolders.push(path_1.default.resolve(__dirname, '../../../test/functionality'));
+    }
+    const { info, program } = (0, doc_types_1.getTypesFromFolder)({ rootFolder: rootFolders, typeNameForMermaid: undefined });
+    return {
+        doc(element, filter) {
+            return (0, doc_types_1.getDocumentationForType)(getNameFromElementIdOrRef(element), info, '', filter);
+        },
+        link(element, fmt, filter) {
+            (0, assert_1.guard)(filter === undefined, 'ElementFilter is not yet supported for link');
+            return (0, doc_types_1.shortLink)(getNameFromElementIdOrRef(element), info, fmt?.codeFont, fmt?.realNameWrapper);
+        },
+        linkM(cls, element, fmt, filter) {
+            const className = cls.prototype.constructor.name;
+            const sep = (fmt?.hideClass) ? ':::' : '::';
+            const fullName = `${className}${sep}${String(element)}`;
+            return this.link(fullName, fmt, filter);
+        },
+        linkFile(element) {
+            return (0, doc_types_1.shortLinkFile)(getNameFromElementIdOrRef(element), info);
+        },
+        hierarchy(element, fmt, filter) {
+            (0, assert_1.guard)(filter === undefined, 'ElementFilter is not yet supported for hierarchy');
+            return (0, doc_types_1.printHierarchy)({
+                program, info,
+                root: getNameFromElementIdOrRef(element),
+                ...fmt
+            });
+        },
+        code(element, fmt, filter) {
+            (0, assert_1.guard)(filter === undefined, 'ElementFilter is not yet supported for code');
+            return (0, doc_types_1.printCodeOfElement)({
+                program, info,
+                ...fmt,
+            }, getNameFromElementIdOrRef(element));
+        },
+        async header(filename, purpose) {
+            const rVersion = (await shell?.usedRVersion())?.format();
+            return (0, doc_auto_gen_1.autoGenHeader)({ filename, purpose, rVersion });
+        },
+        mermaid(element, inlineTypes = doc_types_1.mermaidHide) {
+            return (0, doc_types_1.visualizeMermaidClassDiagram)(info, {
+                typeNameForMermaid: getNameFromElementIdOrRef(element),
+                inlineTypes
+            });
+        }
+    };
+}
+//# sourceMappingURL=doc-context.js.map