feat(wip): staging capabilities ws; mutations

Author: EagleoutIce

.github/workflows/broken-links-and-wiki.yaml

@@ -124,7 +124,7 @@ jobs:
           # so the documentation job builds that one straight onto gh-pages instead
           FLOWR_LANDING_ONLY=1 npm run gen:landing
           # the signature browser is gitignored on purpose (megabytes); only the page and its samples are committed
-          for LANDING in index.html wiki/landing/index.html; do
+          for LANDING in index.html wiki/landing/index.html wiki/capabilities/index.html; do
               if [ -n "$(git status --porcelain -- "$LANDING")" ]; then CHANGED_FILES+=("$LANDING"); fi
           done
           # read in everything from /tmp/flowr-wiki-changed-files.txt and add to CHANGED_FILES

.github/workflows/scripts/run-flowr-command.sh

@@ -159,6 +159,7 @@ if [ "$ACTION" == "doc" ]; then
    git add -f ".nojekyll" "$DOC_OUT/"
    if [ -d "wiki/stats/" ]; then git add -f "wiki/stats/"; fi
    git add -f "index.html"
+   if [ -d "wiki/capabilities/" ]; then git add -f "wiki/capabilities/"; fi
    if [ -d "wiki/sigdb/" ]; then git add -f "wiki/sigdb/"; fi
    if [ -d "wiki/playground/" ]; then git add -f "wiki/playground/"; fi
    git commit -m "Update documentation"
@@ -167,7 +168,7 @@ if [ "$ACTION" == "doc" ]; then
    git checkout --orphan gh-pages-orphan-tmp
    git rm -r --cached . --quiet
    git add -f ".nojekyll" "$DOC_OUT/" "index.html"
-   for extra in "wiki/img" "wiki/stats" "wiki/sigdb" "wiki/playground"; do
+   for extra in "wiki/img" "wiki/stats" "wiki/capabilities" "wiki/sigdb" "wiki/playground"; do
      if [ -d "$extra" ]; then git add -f "$extra"; fi
    done
    git commit -m "Current documentation stage"

README.md

@@ -56,7 +56,7 @@ It offers a wide variety of features, for example:
 
 
     ```text
-    Query: linter (7 ms)
+    Query: linter (27 ms)
        ╰ Deprecated Functions (deprecated-functions): no findings
        ╰ File Path Validity (file-path-validity): no findings
        ╰ Seeded Randomness (seeded-randomness): no findings
@@ -74,7 +74,7 @@ It offers a wide variety of features, for example:
        ╰ Unused Import (unused-import): no findings
        ╰ Unclosed Connection (unclosed-connection): no findings
        ╰ Unescaped Arguments (unescaped-arguments): no findings
-    All queries together required ≈7 ms (1ms accuracy, total 7 ms)
+    All queries together required ≈27 ms (1ms accuracy, total 28 ms)
     ```
 
 
@@ -96,17 +96,17 @@ It offers a wide variety of features, for example:
     
     _Results (prettified and summarized):_
     
-    Query: **linter** (10 ms)\
+    Query: **linter** (60 ms)\
        ╰ **Deprecated Functions** (deprecated-functions): _no findings_\
        ╰ **File Path Validity** (file-path-validity):\
            ╰ certain:\
                ╰ Path `/root/x.txt` at 1.1-23\
-           ╰ _Metadata_: totalReads: 1, totalUnknown: 0, totalWritesBeforeAlways: 0, totalValid: 0, searchTimeMs: 1, processTimeMs: 1\
+           ╰ _Metadata_: totalReads: 1, totalUnknown: 0, totalWritesBeforeAlways: 0, totalValid: 0, searchTimeMs: 1, processTimeMs: 2\
        ╰ **Seeded Randomness** (seeded-randomness): _no findings_\
        ╰ **Absolute Paths** (absolute-file-paths):\
            ╰ certain:\
                ╰ Path `/root/x.txt` at 1.1-23\
-           ╰ _Metadata_: totalConsidered: 1, totalUnknown: 0, searchTimeMs: 0, processTimeMs: 0\
+           ╰ _Metadata_: totalConsidered: 1, totalUnknown: 0, searchTimeMs: 1, processTimeMs: 1\
        ╰ **Unused Definitions** (unused-definitions): _no findings_\
        ╰ **Network Functions** (network-functions): _no findings_\
        ╰ **Dataframe Access Validation** (dataframe-access-validation): _no findings_\
@@ -120,18 +120,17 @@ It offers a wide variety of features, for example:
        ╰ **Unused Import** (unused-import): _no findings_\
        ╰ **Unclosed Connection** (unclosed-connection): _no findings_\
        ╰ **Unescaped Arguments** (unescaped-arguments): _no findings_\
-    _All queries together required ≈10 ms (1ms accuracy, total 11 ms)_
+    _All queries together required ≈60 ms (1ms accuracy, total 62 ms)_
     
     <details> <summary style="color:gray">Show Detailed Results as Json</summary>
     
-    The analysis required _10.6 ms_ (including parsing and normalization and the query) within the generation environment.
+    The analysis required _61.9 ms_ (including parsing and normalization and the query) within the generation environment.
     
     In general, the JSON contains the Ids of the nodes in question as they are present in the normalized AST or the dataflow graph of flowR.
     Please consult the [Interface](https://github.com/flowr-analysis/flowr/wiki/Interface) wiki page for more information on how to get those.
     
     
     
-    
     ```json
     {
       "linter": {
@@ -141,7 +140,7 @@ It offers a wide variety of features, for example:
             ".meta": {
               "builtin": 0,
               "sigdb": 0,
-              "searchTimeMs": 0,
+              "searchTimeMs": 2,
               "processTimeMs": 1
             }
           },
@@ -165,7 +164,7 @@ It offers a wide variety of features, for example:
               "totalWritesBeforeAlways": 0,
               "totalValid": 0,
               "searchTimeMs": 1,
-              "processTimeMs": 1
+              "processTimeMs": 2
             }
           },
           "seeded-randomness": {
@@ -196,8 +195,8 @@ It offers a wide variety of features, for example:
             ".meta": {
               "totalConsidered": 1,
               "totalUnknown": 0,
-              "searchTimeMs": 0,
-              "processTimeMs": 0
+              "searchTimeMs": 1,
+              "processTimeMs": 1
             }
           },
           "unused-definitions": {
@@ -214,7 +213,7 @@ It offers a wide variety of features, for example:
               "totalCalls": 0,
               "totalFunctionDefinitions": 0,
               "searchTimeMs": 0,
-              "processTimeMs": 0
+              "processTimeMs": 1
             }
           },
           "dataframe-access-validation": {
@@ -224,13 +223,13 @@ It offers a wide variety of features, for example:
               "numAccesses": 0,
               "totalAccessed": 0,
               "searchTimeMs": 0,
-              "processTimeMs": 1
+              "processTimeMs": 13
             }
           },
           "dead-code": {
             "results": [],
             ".meta": {
-              "searchTimeMs": 0,
+              "searchTimeMs": 1,
               "processTimeMs": 0
             }
           },
@@ -239,7 +238,7 @@ It offers a wide variety of features, for example:
             ".meta": {
               "numOfUselessLoops": 0,
               "searchTimeMs": 0,
-              "processTimeMs": 0
+              "processTimeMs": 4
             }
           },
           "problematic-inputs": {
@@ -285,7 +284,7 @@ It offers a wide variety of features, for example:
                 "subscript": 0
               },
               "searchTimeMs": 0,
-              "processTimeMs": 3
+              "processTimeMs": 22
             }
           },
           "unused-import": {
@@ -295,7 +294,7 @@ It offers a wide variety of features, for example:
               "totalUnresolved": 0,
               "totalMultiPackage": 0,
               "totalUnused": 0,
-              "searchTimeMs": 0,
+              "searchTimeMs": 2,
               "processTimeMs": 0
             }
           },
@@ -313,17 +312,17 @@ It offers a wide variety of features, for example:
             ".meta": {
               "totalCriticalArguments": 0,
               "totalEscapedArguments": 0,
-              "searchTimeMs": 0,
-              "processTimeMs": 1
+              "searchTimeMs": 1,
+              "processTimeMs": 2
             }
           }
         },
         ".meta": {
-          "timing": 10
+          "timing": 60
         }
       },
       ".meta": {
-        "timing": 10
+        "timing": 60
       }
     }
     ```
@@ -403,7 +402,7 @@ It offers a wide variety of features, for example:
     N <- 10
     for(i in 1:(N-1)) sum <- sum + i + w
     sum
-    All queries together required ≈3 ms (1ms accuracy, total 3 ms)
+    All queries together required ≈17 ms (1ms accuracy, total 18 ms)
     ```
     
     
@@ -765,7 +764,7 @@ It offers a wide variety of features, for example:
     ```
     
     	
-    (The analysis required _3.4 ms_ (including parse and normalize, using the [tree-sitter](https://github.com/flowr-analysis/flowr/wiki/Engines) engine) within the generation environment. No [signature database](https://github.com/flowr-analysis/flowr/wiki/Signature-Database) is mounted for these generated graphs, so `library()` calls attach no package exports; base-R names are still qualified via the generated base-package store (e.g. `acf` as `stats::acf`).)
+    (The analysis required _7.7 ms_ (including parse and normalize, using the [tree-sitter](https://github.com/flowr-analysis/flowr/wiki/Engines) engine) within the generation environment. No [signature database](https://github.com/flowr-analysis/flowr/wiki/Signature-Database) is mounted for these generated graphs, so `library()` calls attach no package exports; base-R names are still qualified via the generated base-package store (e.g. `acf` as `stats::acf`).)
     
     
     

index.html

@@ -32,7 +32,7 @@
     "build:copy-data": "ts-node --transpile-only scripts/sigdb-copy.ts",
     "build:copy-wasm": "ts-node --transpile-only scripts/copy-wasm.ts",
     "gen:base-packages": "ts-node --transpile-only scripts/gen-base-packages.ts",
-    "gen:landing": "ts-node --transpile-only scripts/gen-landing.ts && ts-node --transpile-only scripts/gen-benchmark-index.ts && ts-node --transpile-only scripts/gen-sigdb-index.ts && ts-node --transpile-only scripts/gen-playground.ts",
+    "gen:landing": "ts-node --transpile-only scripts/gen-landing.ts && ts-node --transpile-only scripts/gen-benchmark-index.ts && ts-node --transpile-only scripts/gen-capabilities.ts && ts-node --transpile-only scripts/gen-sigdb-index.ts && ts-node --transpile-only scripts/gen-playground.ts",
     "sigdb:remote": "ts-node --transpile-only scripts/sigdb-remote.ts",
     "sigdb:sync": "ts-node --transpile-only scripts/sigdb-sync.ts",
     "sigdb:publish": "ts-node scripts/publish-sigdb.ts",

package.json

@@ -0,0 +1,24 @@
+/**
+ * Generates the capabilities page at `wiki/capabilities/index.html`, which is what flowR's documentation
+ * points at whenever it says what flowR can and cannot do with R.
+ *
+ * The page is plain static HTML like the landing page. It carries every capability, the tests that demonstrate
+ * it, and its example, which opens in the playground rather than running here.
+ */
+import path from 'path';
+import { template, writePage } from './html-page';
+import { TreeSitterExecutor } from '../src/r-bridge/lang-4.x/tree-sitter/tree-sitter-executor';
+import { capabilitiesAsHtml } from '../src/documentation/doc-capabilities';
+
+const Target = path.join('wiki', 'capabilities', 'index.html');
+
+async function main(): Promise<void> {
+	await TreeSitterExecutor.initTreeSitter();
+	const { body, summary } = await capabilitiesAsHtml(new TreeSitterExecutor());
+	const page = template('landing-capabilities-template.html')
+		.replaceAll('<!--SUMMARY-->', `${summary.fully} of ${summary.total} features fully, ${summary.partially} partially and ${summary.not} not supported.`)
+		.replace('<!--CAPABILITIES-->', body);
+	console.log(`  wrote ${Target} (${(writePage(Target, page) / 1024).toFixed(1)} kB)`);
+}
+
+void main();