@eagleoutice/flowr 2.7.0 → 2.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/README.md +20 -20
  2. package/abstract-interpretation/absint-visitor.d.ts +160 -0
  3. package/abstract-interpretation/absint-visitor.js +279 -0
  4. package/abstract-interpretation/data-frame/dataframe-domain.d.ts +2 -2
  5. package/abstract-interpretation/data-frame/dataframe-domain.js +23 -7
  6. package/abstract-interpretation/data-frame/mappers/access-mapper.d.ts +6 -6
  7. package/abstract-interpretation/data-frame/mappers/access-mapper.js +10 -14
  8. package/abstract-interpretation/data-frame/mappers/arguments.d.ts +10 -9
  9. package/abstract-interpretation/data-frame/mappers/arguments.js +7 -4
  10. package/abstract-interpretation/data-frame/mappers/function-mapper.d.ts +17 -17
  11. package/abstract-interpretation/data-frame/mappers/function-mapper.js +45 -50
  12. package/abstract-interpretation/data-frame/mappers/replacement-mapper.d.ts +7 -7
  13. package/abstract-interpretation/data-frame/mappers/replacement-mapper.js +25 -29
  14. package/abstract-interpretation/data-frame/semantics.js +2 -3
  15. package/abstract-interpretation/data-frame/shape-inference.d.ts +52 -28
  16. package/abstract-interpretation/data-frame/shape-inference.js +67 -90
  17. package/abstract-interpretation/domains/bounded-set-domain.d.ts +2 -2
  18. package/abstract-interpretation/domains/interval-domain.d.ts +2 -2
  19. package/abstract-interpretation/domains/set-range-domain.d.ts +10 -4
  20. package/abstract-interpretation/domains/set-range-domain.js +7 -1
  21. package/abstract-interpretation/domains/set-upper-bound-domain.d.ts +2 -2
  22. package/abstract-interpretation/domains/singleton-domain.d.ts +2 -2
  23. package/benchmark/slicer.js +13 -14
  24. package/cli/common/options.d.ts +431 -8
  25. package/cli/common/options.js +1 -1
  26. package/cli/common/scripts-info.d.ts +431 -7
  27. package/cli/flowr-main-options.d.ts +102 -2
  28. package/cli/flowr.d.ts +102 -2
  29. package/cli/repl/commands/repl-commands.d.ts +25 -0
  30. package/cli/repl/commands/repl-query.js +17 -5
  31. package/cli/wiki.d.ts +13 -0
  32. package/cli/wiki.js +7 -2
  33. package/config.d.ts +4 -4
  34. package/config.js +1 -1
  35. package/control-flow/basic-cfg-guided-visitor.js +7 -8
  36. package/control-flow/control-flow-graph.d.ts +1 -1
  37. package/control-flow/semantic-cfg-guided-visitor.d.ts +1 -1
  38. package/control-flow/semantic-cfg-guided-visitor.js +1 -1
  39. package/dataflow/eval/resolve/alias-tracking.js +1 -1
  40. package/dataflow/internal/linker.d.ts +2 -0
  41. package/dataflow/internal/linker.js +10 -12
  42. package/documentation/doc-capabilities.d.ts +1 -1
  43. package/documentation/doc-readme.d.ts +1 -1
  44. package/documentation/doc-util/doc-cfg.js +1 -1
  45. package/documentation/doc-util/doc-cli-option.d.ts +6 -6
  46. package/documentation/doc-util/doc-cli-option.js +3 -3
  47. package/documentation/doc-util/doc-dfg.d.ts +1 -1
  48. package/documentation/doc-util/doc-files.d.ts +3 -0
  49. package/documentation/doc-util/doc-files.js +4 -1
  50. package/documentation/doc-util/doc-normalized-ast.js +2 -2
  51. package/documentation/issue-linting-rule.d.ts +1 -1
  52. package/documentation/wiki-analyzer.d.ts +1 -1
  53. package/documentation/wiki-cfg.d.ts +1 -1
  54. package/documentation/wiki-core.d.ts +1 -1
  55. package/documentation/wiki-dataflow-graph.d.ts +1 -1
  56. package/documentation/wiki-dataflow-graph.js +6 -6
  57. package/documentation/wiki-engine.d.ts +1 -1
  58. package/documentation/wiki-engine.js +9 -10
  59. package/documentation/wiki-faq.d.ts +1 -1
  60. package/documentation/wiki-interface.d.ts +1 -1
  61. package/documentation/wiki-interface.js +12 -13
  62. package/documentation/wiki-linter.d.ts +1 -1
  63. package/documentation/wiki-linting-and-testing.d.ts +1 -1
  64. package/documentation/wiki-mk/doc-context.d.ts +54 -1
  65. package/documentation/wiki-mk/doc-context.js +17 -0
  66. package/documentation/wiki-mk/doc-maker.d.ts +5 -5
  67. package/documentation/wiki-mk/doc-maker.js +3 -1
  68. package/documentation/wiki-normalized-ast.d.ts +1 -1
  69. package/documentation/wiki-onboarding.d.ts +1 -1
  70. package/documentation/wiki-overview.d.ts +9 -0
  71. package/documentation/wiki-overview.js +248 -0
  72. package/documentation/wiki-query.d.ts +1 -1
  73. package/documentation/wiki-query.js +17 -1
  74. package/documentation/wiki-search.d.ts +1 -1
  75. package/documentation/wiki-setup.d.ts +9 -0
  76. package/documentation/wiki-setup.js +122 -0
  77. package/linter/rules/dataframe-access-validation.d.ts +1 -1
  78. package/linter/rules/dataframe-access-validation.js +8 -10
  79. package/linter/rules/unused-definition.js +1 -1
  80. package/package.json +1 -1
  81. package/project/context/flowr-analyzer-context.d.ts +4 -0
  82. package/project/context/flowr-analyzer-files-context.d.ts +9 -1
  83. package/project/context/flowr-analyzer-files-context.js +4 -0
  84. package/project/context/flowr-file.d.ts +2 -0
  85. package/project/context/flowr-file.js +2 -0
  86. package/project/plugins/file-plugins/{flowr-description-file.d.ts → files/flowr-description-file.d.ts} +1 -1
  87. package/project/plugins/file-plugins/files/flowr-description-file.js +75 -0
  88. package/project/plugins/file-plugins/files/flowr-news-file.d.ts +27 -0
  89. package/project/plugins/file-plugins/files/flowr-news-file.js +152 -0
  90. package/project/plugins/file-plugins/flowr-analyzer-description-file-plugin.d.ts +1 -1
  91. package/project/plugins/file-plugins/flowr-analyzer-description-file-plugin.js +1 -1
  92. package/project/plugins/file-plugins/flowr-analyzer-news-file-plugin.d.ts +23 -0
  93. package/project/plugins/file-plugins/flowr-analyzer-news-file-plugin.js +35 -0
  94. package/project/plugins/file-plugins/notebooks/flowr-analyzer-jupyter-file-plugin.d.ts +1 -1
  95. package/project/plugins/file-plugins/notebooks/flowr-analyzer-jupyter-file-plugin.js +1 -1
  96. package/project/plugins/file-plugins/notebooks/flowr-analyzer-qmd-file-plugin.d.ts +1 -1
  97. package/project/plugins/file-plugins/notebooks/flowr-analyzer-qmd-file-plugin.js +1 -1
  98. package/project/plugins/file-plugins/notebooks/flowr-analyzer-rmd-file-plugin.d.ts +1 -1
  99. package/project/plugins/file-plugins/notebooks/flowr-analyzer-rmd-file-plugin.js +1 -1
  100. package/project/plugins/flowr-analyzer-plugin-defaults.js +2 -0
  101. package/project/plugins/plugin-registry.d.ts +2 -1
  102. package/project/plugins/plugin-registry.js +2 -0
  103. package/project/plugins/project-discovery/flowr-analyzer-project-discovery-plugin.js +7 -1
  104. package/queries/catalog/df-shape-query/df-shape-query-executor.js +4 -2
  105. package/queries/catalog/files-query/files-query-executor.d.ts +6 -0
  106. package/queries/catalog/files-query/files-query-executor.js +49 -0
  107. package/queries/catalog/files-query/files-query-format.d.ts +36 -0
  108. package/queries/catalog/files-query/files-query-format.js +114 -0
  109. package/queries/catalog/linter-query/linter-query-format.js +1 -1
  110. package/queries/query.d.ts +10 -1
  111. package/queries/query.js +3 -1
  112. package/r-bridge/lang-4.x/ast/model/model.d.ts +1 -1
  113. package/r-bridge/lang-4.x/ast/model/processing/decorate.js +8 -8
  114. package/r-bridge/lang-4.x/ast/model/processing/role.d.ts +8 -8
  115. package/r-bridge/lang-4.x/ast/parser/main/internal/functions/normalize-parameter.js +0 -1
  116. package/r-bridge/lang-4.x/tree-sitter/tree-sitter-normalize.js +0 -1
  117. package/statistics/features/supported/data-access/data-access.js +1 -1
  118. package/util/containers.js +1 -1
  119. package/util/files.d.ts +0 -7
  120. package/util/files.js +0 -41
  121. package/util/mermaid/ast.d.ts +3 -2
  122. package/util/mermaid/ast.js +13 -7
  123. package/util/mermaid/cfg.d.ts +3 -2
  124. package/util/mermaid/cfg.js +26 -6
  125. package/util/mermaid/dfg.d.ts +1 -7
  126. package/util/mermaid/dfg.js +7 -3
  127. package/util/mermaid/info.d.ts +17 -0
  128. package/util/mermaid/info.js +5 -0
  129. package/util/prefix.d.ts +9 -5
  130. package/util/prefix.js +14 -6
  131. package/util/r-regex.d.ts +21 -0
  132. package/util/r-regex.js +25 -0
  133. package/util/text/args.js +12 -3
  134. package/util/version.js +1 -1
  135. package/abstract-interpretation/data-frame/absint-info.d.ts +0 -109
  136. package/abstract-interpretation/data-frame/absint-info.js +0 -31
  137. package/abstract-interpretation/data-frame/absint-visitor.d.ts +0 -57
  138. package/abstract-interpretation/data-frame/absint-visitor.js +0 -176
  139. package/abstract-interpretation/data-frame/mappers/assignment-mapper.d.ts +0 -21
  140. package/abstract-interpretation/data-frame/mappers/assignment-mapper.js +0 -34
  141. package/documentation/doc-util/doc-print.d.ts +0 -5
  142. package/documentation/doc-util/doc-print.js +0 -36
  143. package/project/plugins/file-plugins/flowr-description-file.js +0 -37
  144. package/project/plugins/file-plugins/notebooks/notebook.d.ts +0 -0
  145. package/project/plugins/file-plugins/notebooks/notebook.js +0 -2
  146. /package/project/plugins/file-plugins/{notebooks → files}/flowr-jupyter-file.d.ts +0 -0
  147. /package/project/plugins/file-plugins/{notebooks → files}/flowr-jupyter-file.js +0 -0
  148. /package/project/plugins/file-plugins/{notebooks → files}/flowr-rmarkdown-file.d.ts +0 -0
  149. /package/project/plugins/file-plugins/{notebooks → files}/flowr-rmarkdown-file.js +0 -0
@@ -739,7 +739,7 @@ class WikiDataflowGraph extends doc_maker_1.DocMaker {
739
739
  return `
740
740
  This page briefly summarizes flowR's dataflow graph, represented by the ${ctx.link(graph_1.DataflowGraph)} class within the code.
741
741
  In case you want to manually build such a graph (e.g., for testing), you can use the ${ctx.link(dataflowgraph_builder_1.DataflowGraphBuilder)}.
742
- If you are interested in which features we support and which features are still to be worked on, please refer to our [capabilities](${doc_files_1.FlowrWikiBaseRef}/Capabilities) page.
742
+ If you are interested in which features we support and which features are still to be worked on, please refer to our ${ctx.linkPage('wiki/Capabilities')} page.
743
743
  In summary, we discuss the following topics:
744
744
 
745
745
  - [Vertices](#vertices)
@@ -758,12 +758,12 @@ wiki page if you are unsure.
758
758
 
759
759
  > [!TIP]
760
760
  > If you want to investigate the dataflow graph,
761
- > you can either use the [Visual Studio Code extension](${doc_files_1.FlowrGithubBaseRef}/vscode-flowr) or the ${(0, doc_cli_option_1.getReplCommand)('dataflow*')}
762
- > command in the REPL (see the [Interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface) for more information).
763
- > There is also a simplified perspective available with ${(0, doc_cli_option_1.getReplCommand)('dataflowsimple*')} that does not show everything but is easier to read.
761
+ > you can either use the [Visual Studio Code extension](${doc_files_1.FlowrVsCode}) or the ${ctx.replCmd('dataflow*')}
762
+ > command in the REPL (see the ${ctx.linkPage('wiki/Interface', 'Interface wiki page')} for more information).
763
+ > There is also a simplified perspective available with ${ctx.replCmd('dataflowsimple*')} that does not show everything but is easier to read.
764
764
  > When using _flowR_ as a library, you may use the functions in ${(0, doc_files_1.getFilePathMd)('../util/mermaid/dfg.ts')}.
765
765
  >
766
- > If you receive a dataflow graph in its serialized form (e.g., by talking to a [_flowR_ server](${doc_files_1.FlowrWikiBaseRef}/Interface)), you can use ${ctx.link(`${graph_1.DataflowGraph.name}::${graph_1.DataflowGraph.fromJson.name}`, { realNameWrapper: 'i', codeFont: true })} to retrieve the graph from the JSON representation.
766
+ > If you receive a dataflow graph in its serialized form (e.g., by talking to a [_flowR_ server](${doc_files_1.FlowrWikiBaseRef}/Interface)), you can use ${ctx.linkM(graph_1.DataflowGraph, 'fromJson', { realNameWrapper: 'i', codeFont: true })} to retrieve the graph from the JSON representation.
767
767
  >
768
768
  > Also, check out the [${doc_files_1.FlowrGithubGroupName}/sample-analyzer-df-diff](${doc_files_1.FlowrGithubBaseRef}/sample-analyzer-df-diff) repository for a complete example project creating and comparing dataflow graphs.
769
769
 
@@ -773,7 +773,7 @@ ${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'x <- 3\ny <- x + 1\ny')}
773
773
  The above dataflow graph showcases the general gist. We define a dataflow graph as a directed graph G = (V, E), differentiating between ${(0, doc_data_dfg_util_1.getAllVertices)().length} types of vertices V and
774
774
  ${(0, doc_data_dfg_util_1.getAllEdges)().length} types of edges E allowing each vertex to have a single, and each edge to have multiple distinct types.
775
775
  Additionally, every node may have links to its [control dependencies](#control-dependencies) (which you may view as a ${(0, text_1.nth)((0, doc_data_dfg_util_1.getAllEdges)().length + 1)} edge type,
776
- although they are explicitly no data dependency and relate to the [Control Flow Graph](${doc_files_1.FlowrWikiBaseRef}/Control%20Flow%20Graph)).
776
+ although they are explicitly no data dependency and relate to the ${ctx.linkPage('wiki/Control Flow Graph')}.
777
777
 
778
778
  <details open>
779
779
 
@@ -3,7 +3,7 @@ import { DocMaker } from './wiki-mk/doc-maker';
3
3
  /**
4
4
  * https://github.com/flowr-analysis/flowr/wiki/Engines
5
5
  */
6
- export declare class WikiEngine extends DocMaker {
6
+ export declare class WikiEngine extends DocMaker<'wiki/Engines.md'> {
7
7
  constructor();
8
8
  text({ ctx }: DocMakerArgs): string;
9
9
  }
@@ -5,7 +5,6 @@ const shell_1 = require("../r-bridge/shell");
5
5
  const shell_executor_1 = require("../r-bridge/shell-executor");
6
6
  const tree_sitter_executor_1 = require("../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor");
7
7
  const doc_files_1 = require("./doc-util/doc-files");
8
- const doc_cli_option_1 = require("./doc-util/doc-cli-option");
9
8
  const doc_structure_1 = require("./doc-util/doc-structure");
10
9
  const doc_maker_1 = require("./wiki-mk/doc-maker");
11
10
  /**
@@ -30,13 +29,13 @@ we provide the concept of engines.
30
29
  Engines can be loaded with [flowR's configuration file](${doc_files_1.FlowrWikiBaseRef}/Interface#configuring-flowr). Additionally, they
31
30
  are exposed with some command line options (e.g., when using the docker image of flowR):
32
31
 
33
- - ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.r-shell.disabled', false)} to disable the ${ctx.link(shell_1.RShell)} engine
34
- - ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.r-shell.r-path', false)} (which is the canonical version of ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'r-path')})
35
- - ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.disabled', false)} to disable the ${ctx.link(tree_sitter_executor_1.TreeSitterExecutor)} engine
36
- - ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.lax', false)} to use lax parsing with tree-sitter
37
- - ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.wasm-path', false)} pass the path to the wasm of the r grammar of tree-sitter (see [below](#tree-sitter))
38
- - ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)} pass the path to the wasm of tree-sitter (see [below](#tree-sitter))
39
- - ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'default-engine', false)} to set the default engine to use
32
+ - ${ctx.cliOption('flowr', 'engine.r-shell.disabled', false)} to disable the ${ctx.link(shell_1.RShell)} engine
33
+ - ${ctx.cliOption('flowr', 'engine.r-shell.r-path', false)} (which is the canonical version of ${ctx.cliOption('flowr', 'r-path')})
34
+ - ${ctx.cliOption('flowr', 'engine.tree-sitter.disabled', false)} to disable the ${ctx.link(tree_sitter_executor_1.TreeSitterExecutor)} engine
35
+ - ${ctx.cliOption('flowr', 'engine.tree-sitter.lax', false)} to use lax parsing with tree-sitter
36
+ - ${ctx.cliOption('flowr', 'engine.tree-sitter.wasm-path', false)} pass the path to the wasm of the r grammar of tree-sitter (see [below](#tree-sitter))
37
+ - ${ctx.cliOption('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)} pass the path to the wasm of tree-sitter (see [below](#tree-sitter))
38
+ - ${ctx.cliOption('flowr', 'default-engine', false)} to set the default engine to use
40
39
 
41
40
  <a id="tree-sitter"></a>
42
41
  ## Dealing with the Tree-Sitter Engine
@@ -47,8 +46,8 @@ ${(0, doc_structure_1.block)({
47
46
  })}
48
47
 
49
48
  In general, there is no need for you to pass custom paths using either
50
- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.wasm-path', false)} or
51
- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)}.
49
+ ${ctx.cliOption('flowr', 'engine.tree-sitter.wasm-path', false)} or
50
+ ${ctx.cliOption('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)}.
52
51
  However, you may want to experiment with the R grammar or provide a newer
53
52
  one in case that of _flowR_ is outdated.
54
53
 
@@ -2,7 +2,7 @@ import { DocMaker } from './wiki-mk/doc-maker';
2
2
  /**
3
3
  * https://github.com/flowr-analysis/flowr/wiki/FAQ
4
4
  */
5
- export declare class WikiFaq extends DocMaker {
5
+ export declare class WikiFaq extends DocMaker<'wiki/FAQ.md'> {
6
6
  constructor();
7
7
  text(): string;
8
8
  }
@@ -3,7 +3,7 @@ import { DocMaker } from './wiki-mk/doc-maker';
3
3
  /**
4
4
  * https://github.com/flowr-analysis/flowr/wiki/Interface
5
5
  */
6
- export declare class WikiInterface extends DocMaker {
6
+ export declare class WikiInterface extends DocMaker<'wiki/Interface.md'> {
7
7
  constructor();
8
8
  protected text({ shell, ctx, treeSitter }: DocMakerArgs): Promise<string>;
9
9
  }
@@ -94,11 +94,11 @@ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
94
94
 
95
95
  `;
96
96
  }
97
- async function explainRepl(parser) {
97
+ async function explainRepl(parser, ctx) {
98
98
  return `
99
99
  > [!NOTE]
100
- > To execute arbitrary R commands with a repl request, _flowR_ has to be started explicitly with ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'r-session-access')}.
101
- > Please be aware that this introduces a security risk and note that this relies on the [\`r-shell\` engine](${doc_files_1.FlowrWikiBaseRef}/Engines).
100
+ > To execute arbitrary R commands with a repl request, _flowR_ has to be started explicitly with ${ctx.cliOption('flowr', 'r-session-access')}.
101
+ > Please be aware that this introduces a security risk and note that this relies on the ${ctx.linkPage('wiki/Engines', '`r-shell` engine')} .
102
102
 
103
103
  Although primarily meant for users to explore,
104
104
  there is nothing which forbids simply calling _flowR_ as a subprocess to use standard-in, -output, and -error
@@ -108,8 +108,8 @@ with the [REPL Request](#message-request-repl-execution) message).
108
108
  The read-eval-print loop&nbsp;(REPL) works relatively simple.
109
109
  You can submit an expression (using <kbd>Enter</kbd>),
110
110
  which is interpreted as an R&nbsp;expression by default but interpreted as a *command* if it starts with a colon (\`:\`).
111
- The best command to get started with the REPL is ${(0, doc_cli_option_1.getReplCommand)('help')}.
112
- Besides, you can leave the REPL either with the command ${(0, doc_cli_option_1.getReplCommand)('quit')} or by pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> twice.
111
+ The best command to get started with the REPL is ${ctx.replCmd('help')}.
112
+ Besides, you can leave the REPL either with the command ${ctx.replCmd('quit')} or by pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> twice.
113
113
  When writing a *command*, you may press <kbd>Tab</kbd> to get a list of completions, if available.
114
114
  Multiple commands can be entered in a single line by separating them with a semicolon (\`;\`), e.g. \`:parse "x<-2"; :df*\`.
115
115
  If a command is given without R code, the REPL will re-use R code given in a previous command.
@@ -142,20 +142,20 @@ the REPL will re-use previously obtained information and not re-parse the code a
142
142
  ### Example: Retrieving the Dataflow Graph
143
143
 
144
144
  To retrieve a URL to the [mermaid](https://mermaid.js.org/) diagram of the dataflow of a given expression,
145
- use ${(0, doc_cli_option_1.getReplCommand)('dataflow*')} (or ${(0, doc_cli_option_1.getReplCommand)('dataflow')} to get the mermaid code in the cli):
145
+ use ${ctx.replCmd('dataflow*')} (or ${ctx.replCmd('dataflow')} to get the mermaid code in the cli):
146
146
 
147
147
  ${await (0, doc_repl_1.documentReplSession)(parser, [{
148
148
  command: ':dataflow* y <- 1 + x',
149
149
  description: `Retrieve the dataflow graph of the expression \`y <- 1 + x\`. It looks like this:\n${await (0, doc_dfg_1.printDfGraphForCode)(parser, 'y <- 1 + x')}`
150
150
  }])}
151
151
 
152
- For the slicing with ${(0, doc_cli_option_1.getReplCommand)('slicer')}, you have access to the same [magic comments](#slice-magic-comments) as with the [slice request](#message-request-slice).
152
+ For the slicing with ${ctx.replCmd('slicer')}, you have access to the same [magic comments](#slice-magic-comments) as with the [slice request](#message-request-slice).
153
153
 
154
154
  ### Example: Interfacing with the File System
155
155
 
156
- Many commands that allow for an R-expression (like ${(0, doc_cli_option_1.getReplCommand)('dataflow*')}) allow for a file as well
156
+ Many commands that allow for an R-expression (like ${ctx.replCmd('dataflow*')}) allow for a file as well
157
157
  if the argument starts with \`${retriever_1.fileProtocol}\`.
158
- If you are working from the root directory of the _flowR_ repository, the following gives you the parsed AST of the example file using the ${(0, doc_cli_option_1.getReplCommand)('parse')} command:
158
+ If you are working from the root directory of the _flowR_ repository, the following gives you the parsed AST of the example file using the ${ctx.replCmd('parse')} command:
159
159
 
160
160
  ${await (0, doc_repl_1.documentReplSession)(parser, [{
161
161
  command: `:parse ${retriever_1.fileProtocol}test/testfiles/example.R`,
@@ -232,9 +232,9 @@ ${(0, doc_code_1.codeBlock)('json', JSON.stringify({
232
232
  }
233
233
  },
234
234
  abstractInterpretation: {
235
+ wideningThreshold: 4,
235
236
  dataFrame: {
236
237
  maxColNames: 20,
237
- wideningThreshold: 4,
238
238
  readLoadedData: {
239
239
  readExternalFiles: true,
240
240
  maxReadLines: 1_000_000
@@ -436,8 +436,7 @@ class WikiInterface extends doc_maker_1.DocMaker {
436
436
  }
437
437
  async text({ shell, ctx, treeSitter }) {
438
438
  return `
439
- Although far from being as detailed as the in-depth explanation of
440
- [_flowR_](${doc_files_1.FlowrWikiBaseRef}/Core),
439
+ Although far from being as detailed as the in-depth explanation of ${ctx.linkPage('wiki/Core', '_flowR_')},
441
440
  this wiki page explains how to interface with _flowR_ in more detail.
442
441
  In general, command line arguments and other options provide short descriptions on hover over.
443
442
 
@@ -454,7 +453,7 @@ ${await explainServer(shell)}
454
453
  <a id='using-the-repl'></a>
455
454
  ## 💻 Using the REPL
456
455
 
457
- ${await explainRepl(treeSitter)}
456
+ ${await explainRepl(treeSitter, ctx)}
458
457
 
459
458
  <a id='configuring-flowr'></a>
460
459
  ## ⚙️ Configuring FlowR
@@ -3,7 +3,7 @@ import { DocMaker } from './wiki-mk/doc-maker';
3
3
  /**
4
4
  * https://github.com/flowr-analysis/flowr/wiki/Linter
5
5
  */
6
- export declare class WikiLinter extends DocMaker {
6
+ export declare class WikiLinter extends DocMaker<'wiki/Linter.md'> {
7
7
  constructor();
8
8
  protected text({ treeSitter }: DocMakerArgs): Promise<string>;
9
9
  }
@@ -3,7 +3,7 @@ import { DocMaker } from './wiki-mk/doc-maker';
3
3
  /**
4
4
  * https://github.com/flowr-analysis/flowr/wiki/Linting-and-Testing
5
5
  */
6
- export declare class WikiLintingAndTesting extends DocMaker {
6
+ export declare class WikiLintingAndTesting extends DocMaker<'wiki/Linting and Testing.md'> {
7
7
  constructor();
8
8
  protected text({ ctx }: DocMakerArgs): string;
9
9
  }
@@ -1,5 +1,10 @@
1
1
  import type { FnElementInfo, PrintHierarchyArguments, TypeElementKind } from '../doc-util/doc-types';
2
2
  import type { RShell } from '../../r-bridge/shell';
3
+ import type { ValidWikiDocumentTargetsNoSuffix } from '../../cli/wiki';
4
+ import type { PathLike } from 'fs';
5
+ import type { scripts } from '../../cli/common/scripts-info';
6
+ import type { ScriptOptions } from '../doc-util/doc-cli-option';
7
+ import type { ReplCommandNames } from '../../cli/repl/commands/repl-commands';
3
8
  /**
4
9
  * Context available when generating documentation for a wiki in markdown format
5
10
  */
@@ -38,6 +43,9 @@ type NamedPrototype = {
38
43
  type ProtoKeys<T> = T extends {
39
44
  prototype: infer P;
40
45
  } ? keyof P : never;
46
+ type StaticKeys<T> = T extends {
47
+ prototype: infer P;
48
+ } ? Exclude<keyof T, keyof P> : never;
41
49
  /**
42
50
  * Provides methods to generate links, code snippets, and documentation for code elements.
43
51
  * These wrap around a collection of useful helpers originating from the doc utils.
@@ -78,7 +86,7 @@ export interface GeneralDocContext {
78
86
  * Creates a (markdown) link to the `myMethod` member of the `MyClass` class in the code base.
79
87
  * @see {@link GeneralWikiContext#link|link} - for the underlying impl.
80
88
  */
81
- linkM<T extends NamedPrototype>(cls: T, element: ProtoKeys<T>, fmt?: LinkFormat & {
89
+ linkM<T extends NamedPrototype>(cls: T, element: ProtoKeys<T> | StaticKeys<T>, fmt?: LinkFormat & {
82
90
  hideClass?: boolean;
83
91
  }, filter?: ElementFilter): string;
84
92
  /**
@@ -169,6 +177,51 @@ export interface GeneralDocContext {
169
177
  * @param inlineTypes - Optional list of type names to inline in the mermaid diagram (instead of linking them out).
170
178
  */
171
179
  mermaid(element: ElementIdOrRef, inlineTypes?: string[]): string;
180
+ /**
181
+ * Generates a wiki link to another wiki or general docs page.
182
+ * @example
183
+ * ```ts
184
+ * linkWikiPage('wiki/Setup')
185
+ * ```
186
+ * Creates a link to the `wiki/Setup` wiki page with the link text `Setup`.
187
+ * @param pageName - The name of the wiki page to link to.
188
+ * @param linkText - Optional text to display for the link. If not provided, the page name will be used.
189
+ */
190
+ linkPage(pageName: ValidWikiDocumentTargetsNoSuffix, linkText?: string): string;
191
+ /**
192
+ * Generates a link to a code file in the code base.
193
+ * @param path - The path to the code file.
194
+ * @param lineNumber - An optional line number to link to within the file.
195
+ */
196
+ linkCode(path: PathLike, lineNumber?: number): string;
197
+ /**
198
+ * Generates the CLI long option for a given script and option name.
199
+ * @example
200
+ * ```ts
201
+ * cliOption('flowr', 'help')
202
+ * ```
203
+ * Returns `--help` with the accompanying docs.
204
+ * @param scriptName - The name of the script (e.g., 'flowr', 'analyze', etc.)
205
+ * @param optionName - The name of the option for which to generate the long option string.
206
+ * @param withAlias - Whether to include the alias in the output. Default is `false`.
207
+ * @param quote - Whether to wrap the option in backticks. Default is `true`.
208
+ * @see {@link ScriptOptions} - for the valid option names per script.
209
+ * @see {@link getCliLongOptionOf} - for the underlying impl.
210
+ */
211
+ cliOption<ScriptName extends keyof typeof scripts | 'flowr', OptionName extends ScriptOptions<ScriptName>>(scriptName: ScriptName, optionName: OptionName, withAlias?: boolean, quote?: boolean): string;
212
+ /**
213
+ * Generates the REPL command string for a given command name.
214
+ * @example
215
+ * ```ts
216
+ * replCmd('help')
217
+ * ```
218
+ * Returns `:help` with the accompanying docs.
219
+ * @param commandName - The name of the REPL command.
220
+ * @param quote - Whether to wrap the command in backticks. Default is `true`.
221
+ * @param showStar - Whether to show a `[*]` suffix for starred commands. Default is `false`.
222
+ * @see {@link getReplCommand} - for the underlying impl.
223
+ */
224
+ replCmd(commandName: ReplCommandNames, quote?: boolean, showStar?: boolean): string;
172
225
  }
173
226
  /**
174
227
  * Creates a wiki context for generating documentation for code elements.
@@ -8,6 +8,8 @@ const doc_types_1 = require("../doc-util/doc-types");
8
8
  const path_1 = __importDefault(require("path"));
9
9
  const assert_1 = require("../../util/assert");
10
10
  const doc_auto_gen_1 = require("../doc-util/doc-auto-gen");
11
+ const doc_files_1 = require("../doc-util/doc-files");
12
+ const doc_cli_option_1 = require("../doc-util/doc-cli-option");
11
13
  function getNameFromElementIdOrRef(element) {
12
14
  if (typeof element === 'function') {
13
15
  return element.name;
@@ -78,6 +80,21 @@ function makeDocContextForTypes(shell, ...rootFolders) {
78
80
  typeNameForMermaid: getNameFromElementIdOrRef(element),
79
81
  inlineTypes
80
82
  });
83
+ },
84
+ linkPage(pageName, linkText) {
85
+ const text = linkText ?? pageName.split('/').pop() ?? pageName;
86
+ const link = pageName.toLowerCase().replace(/ /g, '-');
87
+ return `[${text}](${doc_files_1.FlowrGithubRef}/${link})`;
88
+ },
89
+ linkCode(path, lineNumber) {
90
+ const lnk = lineNumber ? `${path.toString()}#L${lineNumber}` : path.toString();
91
+ return `[${path.toString()}](${encodeURIComponent(lnk)})`;
92
+ },
93
+ cliOption(scriptName, optionName, withAlias = false, quote = true) {
94
+ return (0, doc_cli_option_1.getCliLongOptionOf)(scriptName, optionName, withAlias, quote);
95
+ },
96
+ replCmd(commandName, quote = true, showStar = false) {
97
+ return (0, doc_cli_option_1.getReplCommand)(commandName, quote, showStar);
81
98
  }
82
99
  };
83
100
  }
@@ -28,9 +28,9 @@ export declare enum WikiChangeType {
28
28
  UnimportantChange = 1,
29
29
  Identical = 2
30
30
  }
31
- export interface DocMakerLike {
31
+ export interface DocMakerLike<Target extends string = string> {
32
32
  make(args: DocMakerArgs & DocMakerOutputArgs): Promise<boolean>;
33
- getTarget(): string;
33
+ getTarget(): Target;
34
34
  getProducer(): string;
35
35
  getWrittenSubfiles(): Set<string>;
36
36
  }
@@ -42,7 +42,7 @@ export interface DocMakerLike {
42
42
  * If this wiki page produces multiple pages ("sub files"), you can use `writeSubFile` inside the `text` method
43
43
  * to write those additional files.
44
44
  */
45
- export declare abstract class DocMaker implements DocMakerLike {
45
+ export declare abstract class DocMaker<Target extends string> implements DocMakerLike<Target> {
46
46
  private readonly target;
47
47
  private readonly filename;
48
48
  private readonly purpose;
@@ -57,11 +57,11 @@ export declare abstract class DocMaker implements DocMakerLike {
57
57
  * @param printHeader - Whether to print the auto-generation header. Default is `true`. Only mark this `false` if you plan to add it yourself.
58
58
  * @protected
59
59
  */
60
- protected constructor(target: PathLike, filename: string, purpose: string, printHeader?: boolean);
60
+ protected constructor(target: Target, filename: string, purpose: string, printHeader?: boolean);
61
61
  /**
62
62
  * Gets the target path where the wiki file will be generated.
63
63
  */
64
- getTarget(): string;
64
+ getTarget(): Target;
65
65
  /**
66
66
  * Gets the name of the producer of this wiki file.
67
67
  */
@@ -17,6 +17,8 @@ const DefaultReplacementPatterns = [
17
17
  [/"[rR]": "\d+\.\d+\.\d+.*?"/g, ''],
18
18
  [/R\s*\d+\.\d+\.\d+/g, ''],
19
19
  [/v\d+\.\d+\.\d+/g, ''],
20
+ // clean paths
21
+ [/%2Fhome%2F([a-zA-Z0-9._-]+%2F)*/g, ''],
20
22
  // async wrapper depends on whether the promise got forfilled already
21
23
  [/async|%20/g, '']
22
24
  ];
@@ -53,7 +55,7 @@ class DocMaker {
53
55
  * Gets the target path where the wiki file will be generated.
54
56
  */
55
57
  getTarget() {
56
- return this.target.toString();
58
+ return this.target;
57
59
  }
58
60
  /**
59
61
  * Gets the name of the producer of this wiki file.
@@ -3,7 +3,7 @@ import { DocMaker } from './wiki-mk/doc-maker';
3
3
  /**
4
4
  * https://github.com/flowr-analysis/flowr/wiki/Normalized-AST
5
5
  */
6
- export declare class WikiNormalizedAst extends DocMaker {
6
+ export declare class WikiNormalizedAst extends DocMaker<'wiki/Normalized AST.md'> {
7
7
  constructor();
8
8
  protected text({ ctx, treeSitter }: DocMakerArgs): Promise<string>;
9
9
  }
@@ -2,7 +2,7 @@ import { DocMaker } from './wiki-mk/doc-maker';
2
2
  /**
3
3
  * https://github.com/flowr-analysis/flowr/wiki/Onboarding
4
4
  */
5
- export declare class WikiOnboarding extends DocMaker {
5
+ export declare class WikiOnboarding extends DocMaker<'wiki/Onboarding.md'> {
6
6
  constructor();
7
7
  text(): string;
8
8
  }
@@ -0,0 +1,9 @@
1
+ import type { DocMakerArgs } from './wiki-mk/doc-maker';
2
+ import { DocMaker } from './wiki-mk/doc-maker';
3
+ /**
4
+ * https://github.com/flowr-analysis/flowr/wiki/Overview
5
+ */
6
+ export declare class WikiOverview extends DocMaker<'wiki/Overview.md'> {
7
+ constructor();
8
+ text({ ctx }: DocMakerArgs): string;
9
+ }