From ccb854261545f9ea8887929e65a219adc0214cad Mon Sep 17 00:00:00 2001 From: Daniel O'Grady <103028279+daogrady@users.noreply.github.com> Date: Tue, 1 Oct 2024 17:05:15 +0200 Subject: [PATCH] Workflow to add the output for `cds-typer --help` in typer section (#1294) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Co-authored-by: Lothar Bender Co-authored-by: Christian Georgi --- .github/typer/grab-typer-synopsis.js | 46 ++++++++++++++++ .github/workflows/extract-docs.yml | 52 ++++++++++++++++++ tools/cds-typer.md | 79 +--------------------------- tools/cds-typer_help-output.md | 78 +++++++++++++++++++++++++++ 4 files changed, 177 insertions(+), 78 deletions(-) create mode 100755 .github/typer/grab-typer-synopsis.js create mode 100644 .github/workflows/extract-docs.yml create mode 100644 tools/cds-typer_help-output.md diff --git a/.github/typer/grab-typer-synopsis.js b/.github/typer/grab-typer-synopsis.js new file mode 100755 index 000000000..3ce64f4ec --- /dev/null +++ b/.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) => [ + '', + '```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}`) +} diff --git a/.github/workflows/extract-docs.yml b/.github/workflows/extract-docs.yml new file mode 100644 index 000000000..ae99cf4cf --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/tools/cds-typer.md b/tools/cds-typer.md index 8019cf1d9..47e2c4dd1 100644 --- a/tools/cds-typer.md +++ b/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: - - -```log -> @cap-js/cds-typer@0.26.0 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: - (default: structured) - - Whether to resolve inline type declarations - flat: (x_a, x_b, ...) - or structured: (x: {a, b}). - - --IEEE754Compatible - --ieee754compatible: - (default: false) - - If set to true, floating point properties are generated - as IEEE754 compatible '(number | string)' instead of 'number'. - - --jsConfigPath - --js_config_path: - - 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: - (default: ./) - - Root directory to write the generated files to. - - --propertiesOptional - --properties_optional: - (default: true) - - If set to true, properties in entities are - always generated as optional (a?: T). - - --useEntitiesProxy - --use_entities_proxy: - (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. -``` + ::: ### Configuration diff --git a/tools/cds-typer_help-output.md b/tools/cds-typer_help-output.md new file mode 100644 index 000000000..0aa209592 --- /dev/null +++ b/tools/cds-typer_help-output.md @@ -0,0 +1,78 @@ + +```log +> @cap-js/cds-typer@0.26.0 --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: + (default: structured) + + Whether to resolve inline type declarations + flat: (x_a, x_b, ...) + or structured: (x: {a, b}). + + --IEEE754Compatible + --ieee754compatible: + (default: false) + + If set to true, floating point properties are generated + as IEEE754 compatible '(number | string)' instead of 'number'. + + --jsConfigPath + --js_config_path: + + 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: + (default: ./) + + Root directory to write the generated files to. + + --propertiesOptional + --properties_optional: + (default: true) + + If set to true, properties in entities are + always generated as optional (a?: T). + + --useEntitiesProxy + --use_entities_proxy: + (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. + +``` \ No newline at end of file