Workflow to add the output for cds-typer --help in typer section (#…

…1294)

The [documentation for
cds-typer](https://cap.cloud.sap/docs/tools/cds-typer#usage-options)
contains the output of calling `cds-typer --help`. This improves
searchability for both search engines and AI. We currently update this
part of the docs from time to time, so as of now, the help text could be
out of date for some time before being brought up to date.

This PR introduces an action that can be triggered manually and
automatically runs every Wednesday morning to automatically grab the
latest version of the help text. If there are any updates, it will open
a PR with the new content.

---------

Co-authored-by: René Jeglinsky <[email protected]>
Co-authored-by: Lothar Bender <[email protected]>
Co-authored-by: Christian Georgi <[email protected]>

.github/typer/grab-typer-synopsis.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+// cds-typer Synopsis Extractor
+// ============================
+// runs "npx @cap-js/cds-typer --help" to extract the synopsis and version
+// of the latest cds-typer version and writes it to a markdown file
+// that is included in the cds-typer documentation page.
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as proc from 'node:child_process'
+import * as util from 'node:util'
+
+const exec = util.promisify(proc.exec)
+const tool = '@cap-js/cds-typer'
+const includingFile = path.join('tools', 'cds-typer.md')
+const synopsisFile = path.join('tools', 'cds-typer_help-output.md')
+
+const toMarkdown = (version, synopsis) => [
+    '<!-- this file is automatically generated and updated by a github action -->',
+    '```log',
+    `> ${tool}@${version} --help`,
+    '',
+    synopsis,
+    '```'
+].join('\n')
+
+try {
+    const { stdout: version } = await exec(`npx ${tool} --version`)
+    const { stdout: synopsis } = await exec(`npx ${tool} --help`)
+
+    // some very basic plausibility checks to make sure we don't
+    // end up with garbage or npx errors in the markdown
+    if (!/\d+\.\d+\.\d+/.test(version)) {
+        throw new Error(`unexpected version: ${version}`)
+    }
+    if (!synopsis || !/SYNOPSIS/.test(synopsis)) {
+        throw new Error(`unexpected synopsis: ${synopsis}`)
+    }
+    if (!fs.existsSync(includingFile)) {
+        throw new Error(`could not find file '${includingFile}', where to include the synopsis. Has the documentation for cds-typer moved?`)
+    }
+    fs.writeFileSync(synopsisFile, toMarkdown(version.trim(), synopsis))
+} catch (e) {
+    console.error(`could not run cds-typer to generate synopsis: ${e.message}`)
+}

.github/workflows/extract-docs.yml

@@ -0,0 +1,52 @@
+name: PR Latest cds-typer Output
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Runs every Wednesday at 02:45 AM (UTC)
+    - cron: '45 2 * * 3'
+
+jobs:
+  run_script_and_create_pr:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Extract cds-typer --help text
+        run: node .github/typer/grab-typer-synopsis.js
+
+      - name: Check for changes
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          git add -A
+          if git diff --cached --exit-code; then
+            echo "No changes detected. Exiting."
+            exit 0
+          fi
+
+      - name: Commit changes
+        run: |
+          git commit -m "Update cds-typer synopsis"
+      
+      - name: Push changes
+        run: |
+          BRANCH_NAME="update-cds-typer-synopsis-$(date +'%Y%m%d%H%M%S')"
+          git checkout -b "$BRANCH_NAME"
+          git push origin "$BRANCH_NAME"
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ steps.push_changes.outputs.BRANCH_NAME }}
+          title: "chore: Update synopsis for cds-typer"
+          body: "Updates the output of `cds-typer --help` to the latest version."
+          base: main

tools/cds-typer.md

@@ -310,84 +310,7 @@ npx @cap-js/cds-typer /home/mybookshop/db/schema.cds --outputDirectory /home/myb
 The CLI offers several parameters which you can list using the `--help` parameter.
 
 ::: details You should then see the following output:
-
-<!-- TODO: automatically pull command line options from cds-typer --help -->
-```log
-> @cap-js/[email protected] cli
-> node lib/cli.js --help
-SYNOPSIS
-
-  cds-typer [cds file | "*"]
-
-  Generates type information based on a CDS model.
-  Call with at least one positional parameter pointing
-  to the (root) CDS file you want to compile.
-
-OPTIONS
-
-  --help
-
-    This text.
-
-  --inlineDeclarations
-  --inline_declarations: <flat | structured>
-    (default: structured)
-
-    Whether to resolve inline type declarations
-    flat: (x_a, x_b, ...)
-    or structured: (x: {a, b}).
-
-  --IEEE754Compatible
-  --ieee754compatible: <true | false>
-    (default: false)
-
-    If set to true, floating point properties are generated
-    as IEEE754 compatible '(number | string)' instead of 'number'.
-
-  --jsConfigPath
-  --js_config_path: <string>
-
-    Path to where the jsconfig.json should be written.
-    If specified, cds-typer will create a jsconfig.json file and
-    set it up to restrict property usage in types entities to
-    existing properties only.
-
-  --logLevel
-  --log_level SILENT | ERROR | WARN | INFO | DEBUG | TRACE | SILLY | VERBOSE
-    (default: ERROR)
-
-    Minimum log level that is printed.
-    The default is only used if no explicit value is passed
-    and there is no configuration passed via cds.env either.
-
-  --outputDirectory
-  --output_directory: <string>
-    (default: ./)
-
-    Root directory to write the generated files to.
-
-  --propertiesOptional
-  --properties_optional: <true | false>
-    (default: true)
-
-    If set to true, properties in entities are
-    always generated as optional (a?: T).
-
-  --useEntitiesProxy
-  --use_entities_proxy: <true | false>
-    (default: false)
-
-    If set to true the 'cds.entities' exports in the generated 'index.js'
-    files will be wrapped in 'Proxy' objects
-    so static import/require calls can be used everywhere.
-    
-    WARNING: entity properties can still only be accessed after
-    'cds.entities' has been loaded
-
-  --version
-
-    Prints the version of this tool.
-```
+<!--@include: ./cds-typer_help-output.md-->
 :::
 
 ### Configuration

tools/cds-typer_help-output.md

@@ -0,0 +1,78 @@
+<!-- this file is automatically generated and updated by a github action -->
+```log
+> @cap-js/[email protected] --help
+
+SYNOPSIS
+
+  cds-typer [cds file | "*"]
+
+  Generates type information based on a CDS model.
+  Call with at least one positional parameter pointing
+  to the (root) CDS file you want to compile.
+
+OPTIONS
+
+  --help
+
+    This text.
+
+  --inlineDeclarations
+  --inline_declarations: <flat | structured>
+    (default: structured)
+
+    Whether to resolve inline type declarations
+    flat: (x_a, x_b, ...)
+    or structured: (x: {a, b}).
+
+  --IEEE754Compatible
+  --ieee754compatible: <true | false>
+    (default: false)
+
+    If set to true, floating point properties are generated
+    as IEEE754 compatible '(number | string)' instead of 'number'.
+
+  --jsConfigPath
+  --js_config_path: <string>
+
+    Path to where the jsconfig.json should be written.
+    If specified, cds-typer will create a jsconfig.json file and
+    set it up to restrict property usage in types entities to
+    existing properties only.
+
+  --logLevel
+  --log_level SILENT | ERROR | WARN | INFO | DEBUG | TRACE | SILLY | VERBOSE
+    (default: ERROR)
+
+    Minimum log level that is printed.
+    The default is only used if no explicit value is passed
+    and there is no configuration passed via cds.env either.
+
+  --outputDirectory
+  --output_directory: <string>
+    (default: ./)
+
+    Root directory to write the generated files to.
+
+  --propertiesOptional
+  --properties_optional: <true | false>
+    (default: true)
+
+    If set to true, properties in entities are
+    always generated as optional (a?: T).
+
+  --useEntitiesProxy
+  --use_entities_proxy: <true | false>
+    (default: false)
+
+    If set to true the 'cds.entities' exports in the generated 'index.js'
+    files will be wrapped in 'Proxy' objects
+    so static import/require calls can be used everywhere.
+    
+    WARNING: entity properties can still only be accessed after
+    'cds.entities' has been loaded
+
+  --version
+
+    Prints the version of this tool.
+
+```