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