@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.
- package/README.md +20 -20
- package/abstract-interpretation/absint-visitor.d.ts +160 -0
- package/abstract-interpretation/absint-visitor.js +279 -0
- package/abstract-interpretation/data-frame/dataframe-domain.d.ts +2 -2
- package/abstract-interpretation/data-frame/dataframe-domain.js +23 -7
- package/abstract-interpretation/data-frame/mappers/access-mapper.d.ts +6 -6
- package/abstract-interpretation/data-frame/mappers/access-mapper.js +10 -14
- package/abstract-interpretation/data-frame/mappers/arguments.d.ts +10 -9
- package/abstract-interpretation/data-frame/mappers/arguments.js +7 -4
- package/abstract-interpretation/data-frame/mappers/function-mapper.d.ts +17 -17
- package/abstract-interpretation/data-frame/mappers/function-mapper.js +45 -50
- package/abstract-interpretation/data-frame/mappers/replacement-mapper.d.ts +7 -7
- package/abstract-interpretation/data-frame/mappers/replacement-mapper.js +25 -29
- package/abstract-interpretation/data-frame/semantics.js +2 -3
- package/abstract-interpretation/data-frame/shape-inference.d.ts +52 -28
- package/abstract-interpretation/data-frame/shape-inference.js +67 -90
- package/abstract-interpretation/domains/bounded-set-domain.d.ts +2 -2
- package/abstract-interpretation/domains/interval-domain.d.ts +2 -2
- package/abstract-interpretation/domains/set-range-domain.d.ts +10 -4
- package/abstract-interpretation/domains/set-range-domain.js +7 -1
- package/abstract-interpretation/domains/set-upper-bound-domain.d.ts +2 -2
- package/abstract-interpretation/domains/singleton-domain.d.ts +2 -2
- package/benchmark/slicer.js +13 -14
- package/cli/common/options.d.ts +431 -8
- package/cli/common/options.js +1 -1
- package/cli/common/scripts-info.d.ts +431 -7
- package/cli/flowr-main-options.d.ts +102 -2
- package/cli/flowr.d.ts +102 -2
- package/cli/repl/commands/repl-commands.d.ts +25 -0
- package/cli/repl/commands/repl-query.js +17 -5
- package/cli/wiki.d.ts +13 -0
- package/cli/wiki.js +7 -2
- package/config.d.ts +4 -4
- package/config.js +1 -1
- package/control-flow/basic-cfg-guided-visitor.js +7 -8
- package/control-flow/control-flow-graph.d.ts +1 -1
- package/control-flow/semantic-cfg-guided-visitor.d.ts +1 -1
- package/control-flow/semantic-cfg-guided-visitor.js +1 -1
- package/dataflow/eval/resolve/alias-tracking.js +1 -1
- package/dataflow/internal/linker.d.ts +2 -0
- package/dataflow/internal/linker.js +10 -12
- package/documentation/doc-capabilities.d.ts +1 -1
- package/documentation/doc-readme.d.ts +1 -1
- package/documentation/doc-util/doc-cfg.js +1 -1
- package/documentation/doc-util/doc-cli-option.d.ts +6 -6
- package/documentation/doc-util/doc-cli-option.js +3 -3
- package/documentation/doc-util/doc-dfg.d.ts +1 -1
- package/documentation/doc-util/doc-files.d.ts +3 -0
- package/documentation/doc-util/doc-files.js +4 -1
- package/documentation/doc-util/doc-normalized-ast.js +2 -2
- package/documentation/issue-linting-rule.d.ts +1 -1
- package/documentation/wiki-analyzer.d.ts +1 -1
- package/documentation/wiki-cfg.d.ts +1 -1
- package/documentation/wiki-core.d.ts +1 -1
- package/documentation/wiki-dataflow-graph.d.ts +1 -1
- package/documentation/wiki-dataflow-graph.js +6 -6
- package/documentation/wiki-engine.d.ts +1 -1
- package/documentation/wiki-engine.js +9 -10
- package/documentation/wiki-faq.d.ts +1 -1
- package/documentation/wiki-interface.d.ts +1 -1
- package/documentation/wiki-interface.js +12 -13
- package/documentation/wiki-linter.d.ts +1 -1
- package/documentation/wiki-linting-and-testing.d.ts +1 -1
- package/documentation/wiki-mk/doc-context.d.ts +54 -1
- package/documentation/wiki-mk/doc-context.js +17 -0
- package/documentation/wiki-mk/doc-maker.d.ts +5 -5
- package/documentation/wiki-mk/doc-maker.js +3 -1
- package/documentation/wiki-normalized-ast.d.ts +1 -1
- package/documentation/wiki-onboarding.d.ts +1 -1
- package/documentation/wiki-overview.d.ts +9 -0
- package/documentation/wiki-overview.js +248 -0
- package/documentation/wiki-query.d.ts +1 -1
- package/documentation/wiki-query.js +17 -1
- package/documentation/wiki-search.d.ts +1 -1
- package/documentation/wiki-setup.d.ts +9 -0
- package/documentation/wiki-setup.js +122 -0
- package/linter/rules/dataframe-access-validation.d.ts +1 -1
- package/linter/rules/dataframe-access-validation.js +8 -10
- package/linter/rules/unused-definition.js +1 -1
- package/package.json +1 -1
- package/project/context/flowr-analyzer-context.d.ts +4 -0
- package/project/context/flowr-analyzer-files-context.d.ts +9 -1
- package/project/context/flowr-analyzer-files-context.js +4 -0
- package/project/context/flowr-file.d.ts +2 -0
- package/project/context/flowr-file.js +2 -0
- package/project/plugins/file-plugins/{flowr-description-file.d.ts → files/flowr-description-file.d.ts} +1 -1
- package/project/plugins/file-plugins/files/flowr-description-file.js +75 -0
- package/project/plugins/file-plugins/files/flowr-news-file.d.ts +27 -0
- package/project/plugins/file-plugins/files/flowr-news-file.js +152 -0
- package/project/plugins/file-plugins/flowr-analyzer-description-file-plugin.d.ts +1 -1
- package/project/plugins/file-plugins/flowr-analyzer-description-file-plugin.js +1 -1
- package/project/plugins/file-plugins/flowr-analyzer-news-file-plugin.d.ts +23 -0
- package/project/plugins/file-plugins/flowr-analyzer-news-file-plugin.js +35 -0
- package/project/plugins/file-plugins/notebooks/flowr-analyzer-jupyter-file-plugin.d.ts +1 -1
- package/project/plugins/file-plugins/notebooks/flowr-analyzer-jupyter-file-plugin.js +1 -1
- package/project/plugins/file-plugins/notebooks/flowr-analyzer-qmd-file-plugin.d.ts +1 -1
- package/project/plugins/file-plugins/notebooks/flowr-analyzer-qmd-file-plugin.js +1 -1
- package/project/plugins/file-plugins/notebooks/flowr-analyzer-rmd-file-plugin.d.ts +1 -1
- package/project/plugins/file-plugins/notebooks/flowr-analyzer-rmd-file-plugin.js +1 -1
- package/project/plugins/flowr-analyzer-plugin-defaults.js +2 -0
- package/project/plugins/plugin-registry.d.ts +2 -1
- package/project/plugins/plugin-registry.js +2 -0
- package/project/plugins/project-discovery/flowr-analyzer-project-discovery-plugin.js +7 -1
- package/queries/catalog/df-shape-query/df-shape-query-executor.js +4 -2
- package/queries/catalog/files-query/files-query-executor.d.ts +6 -0
- package/queries/catalog/files-query/files-query-executor.js +49 -0
- package/queries/catalog/files-query/files-query-format.d.ts +36 -0
- package/queries/catalog/files-query/files-query-format.js +114 -0
- package/queries/catalog/linter-query/linter-query-format.js +1 -1
- package/queries/query.d.ts +10 -1
- package/queries/query.js +3 -1
- package/r-bridge/lang-4.x/ast/model/model.d.ts +1 -1
- package/r-bridge/lang-4.x/ast/model/processing/decorate.js +8 -8
- package/r-bridge/lang-4.x/ast/model/processing/role.d.ts +8 -8
- package/r-bridge/lang-4.x/ast/parser/main/internal/functions/normalize-parameter.js +0 -1
- package/r-bridge/lang-4.x/tree-sitter/tree-sitter-normalize.js +0 -1
- package/statistics/features/supported/data-access/data-access.js +1 -1
- package/util/containers.js +1 -1
- package/util/files.d.ts +0 -7
- package/util/files.js +0 -41
- package/util/mermaid/ast.d.ts +3 -2
- package/util/mermaid/ast.js +13 -7
- package/util/mermaid/cfg.d.ts +3 -2
- package/util/mermaid/cfg.js +26 -6
- package/util/mermaid/dfg.d.ts +1 -7
- package/util/mermaid/dfg.js +7 -3
- package/util/mermaid/info.d.ts +17 -0
- package/util/mermaid/info.js +5 -0
- package/util/prefix.d.ts +9 -5
- package/util/prefix.js +14 -6
- package/util/r-regex.d.ts +21 -0
- package/util/r-regex.js +25 -0
- package/util/text/args.js +12 -3
- package/util/version.js +1 -1
- package/abstract-interpretation/data-frame/absint-info.d.ts +0 -109
- package/abstract-interpretation/data-frame/absint-info.js +0 -31
- package/abstract-interpretation/data-frame/absint-visitor.d.ts +0 -57
- package/abstract-interpretation/data-frame/absint-visitor.js +0 -176
- package/abstract-interpretation/data-frame/mappers/assignment-mapper.d.ts +0 -21
- package/abstract-interpretation/data-frame/mappers/assignment-mapper.js +0 -34
- package/documentation/doc-util/doc-print.d.ts +0 -5
- package/documentation/doc-util/doc-print.js +0 -36
- package/project/plugins/file-plugins/flowr-description-file.js +0 -37
- package/project/plugins/file-plugins/notebooks/notebook.d.ts +0 -0
- package/project/plugins/file-plugins/notebooks/notebook.js +0 -2
- /package/project/plugins/file-plugins/{notebooks → files}/flowr-jupyter-file.d.ts +0 -0
- /package/project/plugins/file-plugins/{notebooks → files}/flowr-jupyter-file.js +0 -0
- /package/project/plugins/file-plugins/{notebooks → files}/flowr-rmarkdown-file.d.ts +0 -0
- /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
|
|
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.
|
|
762
|
-
> command in the REPL (see the
|
|
763
|
-
> There is also a simplified perspective available with ${
|
|
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.
|
|
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
|
|
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
|
-
- ${
|
|
34
|
-
- ${
|
|
35
|
-
- ${
|
|
36
|
-
- ${
|
|
37
|
-
- ${
|
|
38
|
-
- ${
|
|
39
|
-
- ${
|
|
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
|
-
${
|
|
51
|
-
${
|
|
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
|
|
|
@@ -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 ${
|
|
101
|
-
> Please be aware that this introduces a security risk and note that this relies on the
|
|
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 (REPL) works relatively simple.
|
|
109
109
|
You can submit an expression (using <kbd>Enter</kbd>),
|
|
110
110
|
which is interpreted as an R 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 ${
|
|
112
|
-
Besides, you can leave the REPL either with the command ${
|
|
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 ${
|
|
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 ${
|
|
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 ${
|
|
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 ${
|
|
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():
|
|
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:
|
|
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():
|
|
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
|
|
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
|
+
}
|