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

.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@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        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: "Automated PR: Update synopsis for cds-typer"
+          body: "This PR was automatically generated and 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.
+
+```