Skip to content

Commit 2bc145a

Browse files
chgeochgeo
committed
Generic CLI output grabbing
1 parent 4130cf9 commit 2bc145a

File tree

9 files changed

+214
-137
lines changed

9 files changed

+214
-137
lines changed

‎.github/cli/grab-cli-texts.js

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
#!/usr/bin/env node
2+
3+
// CLI Help Extractor
4+
// ============================
5+
// runs "npm exec <tool> --help" to extract the synopsis and version
6+
// of the latest tool version and writes it to a markdown file
7+
// that is included in a documentation page.
8+
9+
import * as proc from 'node:child_process'
10+
import * as util from 'node:util'
11+
12+
const exec = util.promisify(proc.exec)
13+
const pkg = process.argv[2]
14+
if (!pkg) throw new Error('Missing package')
15+
const cmd = process.argv[3] || pkg.split('/').pop()
16+
const cwd = process.argv[4] || process.cwd()
17+
const unstyled = process.argv.some(a => a === '--unstyled')
18+
19+
const toMarkdown = (version, str) => [
20+
'<!-- this file is automatically generated and updated by a github action -->',
21+
`${unstyled ? '```log' : '<pre class="log">'}`,
22+
`> ${pkg}@${version} ${cmd}`,
23+
'',
24+
str
25+
.replace(/\n.*home.*[|:].*/g, '') // remove absolute cds home path as it's system-specific
26+
.replace(/\<(.*?)\>/g, '&lt;$1&gt;') // <foo> -> &lt;foo&gt;
27+
.replace(/^\x1b\[1m(.*?)\x1b\[0m\n/gm, '<strong>$1</strong>') // bold at beginning of line -> strong
28+
.replace(/(\s*)\x1b\[4m(.*?)\x1b\[0m/g, '$1<i>$2</i>') // underline -> i
29+
.replace(/(\s*)\x1b\[\d+m(.*?)\x1b\[0m/g, '$1<em>$2</em>') // other colors -> em
30+
, `${unstyled ? '```' : '</pre>'}`
31+
].join('\n')
32+
33+
try {
34+
const cmdString = `npm exec --package=${pkg} -c "${cmd}"`
35+
const { stdout: version } = await exec(`npm view ${pkg} version`)
36+
const { stdout: cmdOut } = await exec(cmdString, {cwd, env: { FORCE_COLOR: 'true', ...process.env }})
37+
38+
// some very basic plausibility checks to make sure we don't
39+
// end up with garbage or npx errors in the markdown
40+
if (!/\d+\.\d+\.\d+/.test(version)) {
41+
throw new Error(`unexpected version: ${version}`)
42+
}
43+
if (!cmdOut) {
44+
throw new Error(`no output from: ${cmdString}`)
45+
}
46+
if (cmd.includes('help') && !/SYNOPSIS|USAGE/.test(cmdOut)) {
47+
throw new Error(`unexpected synopsis: ${cmdOut}`)
48+
}
49+
console.log(toMarkdown(version.trim(), cmdOut.trim()))
50+
} catch (e) {
51+
console.error(`could not generate synopsis: ${e.message}`, e)
52+
}

‎.github/workflows/extract-docs.yml

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
1-
name: PR Latest cds-typer Output
1+
name: Update CLI Texts
22

33
on:
44
workflow_dispatch:
55
schedule:
66
# Runs every Wednesday at 02:45 AM (UTC)
77
- cron: '45 2 * * 3'
88

9+
permissions:
10+
contents: write
11+
pull-requests: write
12+
913
jobs:
1014
run_script_and_create_pr:
1115
runs-on: ubuntu-latest
@@ -19,8 +23,15 @@ jobs:
1923
with:
2024
node-version: '20'
2125

22-
- name: Extract cds-typer --help text
23-
run: node .github/typer/grab-typer-synopsis.js
26+
- name: Extract CLI texts
27+
run: |
28+
npm i -g @sap/cds-dk
29+
pushd /tmp && rm -rf your-project && cds init your-project && pushd your-project && npm i && popd && popd
30+
.github/cli/grab-cli-texts.js @cap-js/cds-typer "cds-typer --help" /tmp/your-project > tools/assets/help/cds-typer.out.md
31+
.github/cli/grab-cli-texts.js @sap/cds-dk "cds --help" /tmp/your-project > tools/assets/help/cds-help.out.md
32+
.github/cli/grab-cli-texts.js @sap/cds-dk "cds watch --help" /tmp/your-project > tools/assets/help/cds-watch.out.md
33+
.github/cli/grab-cli-texts.js @sap/cds-dk "cds version" /tmp/your-project > tools/assets/help/cds-version.out.md
34+
.github/cli/grab-cli-texts.js @sap/cds-dk "cds version --markdown" /tmp/your-project > tools/assets/help/cds-version-md.out.md
2435
2536
- name: Check for changes
2637
run: |
@@ -34,19 +45,21 @@ jobs:
3445
3546
- name: Commit changes
3647
run: |
37-
git commit -m "Update cds-typer synopsis"
38-
48+
git commit -m "Update CLI texts"
49+
3950
- name: Push changes
51+
id: push_changes
4052
run: |
41-
BRANCH_NAME="update-cds-typer-synopsis-$(date +'%Y%m%d%H%M%S')"
53+
BRANCH_NAME="update-cds-cli-texts-$(date +'%Y%m%d%H%M%S')"
4254
git checkout -b "$BRANCH_NAME"
4355
git push origin "$BRANCH_NAME"
56+
echo "::set-output name=BRANCH_NAME::$BRANCH_NAME"
4457
4558
- name: Create Pull Request
46-
uses: peter-evans/create-pull-request@v5
59+
uses: peter-evans/create-pull-request@v7
4760
with:
4861
token: ${{ secrets.GITHUB_TOKEN }}
4962
branch: ${{ steps.push_changes.outputs.BRANCH_NAME }}
50-
title: "chore: Update synopsis for cds-typer"
51-
body: "Updates the output of `cds-typer --help` to the latest version."
63+
title: "chore: Update CLI texts"
64+
body: "Updates the output of cds CLI texts to the latest version."
5265
base: main

‎tools/assets/help/cds-help.out.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<!-- this file is automatically generated and updated by a github action -->
2+
<pre class="log">
3+
> @sap/[email protected] cds --help --help
4+
5+
<strong>USAGE</strong>
6+
<em>cds</em> &lt;command&gt; [&lt;args&gt;]
7+
<em>cds</em> &lt;src&gt; = <em>cds compile</em> &lt;src&gt;
8+
<em>cds</em> = <em>cds help</em>
9+
10+
<strong>COMMANDS</strong>
11+
<em>i</em> | <em>init</em> jump-start cds-based projects
12+
<em>a</em> | <em>add</em> add a feature to an existing project
13+
<em> </em> | <em>gen</em> generate models/data using a descriptive prompt [beta]
14+
<em>y</em> | <em>bind</em> bind application to remote services
15+
<em>m</em> | <em>import</em> add models from external sources
16+
<em>c</em> | <em>compile</em> compile cds models to different outputs
17+
<em>p</em> | <em>parse</em> parses given cds models
18+
<em>s</em> | <em>serve</em> run your services in local server
19+
<em>w</em> | <em>watch</em> run and restart on file changes
20+
<em> </em> | <em>mock</em> call <i>cds serve</i> with mocked service
21+
<em>r</em> | <em>repl</em> read-eval-event loop
22+
<em>e</em> | <em>env</em> inspect effective configuration
23+
<em>b</em> | <em>build</em> prepare for deployment
24+
<em>d</em> | <em>deploy</em> deploy to databases or cloud
25+
<em> </em> | <em>subscribe</em> subscribe a tenant to a multitenant SaaS app
26+
<em> </em> | <em>unsubscribe</em> unsubscribe a tenant from a multitenant SaaS app
27+
<em>l</em> | <em>login</em> login to extensible multitenant SaaS app
28+
<em> </em> | <em>logout</em> logout from extensible multitenant SaaS app
29+
<em> </em> | <em>pull</em> pull base model of extensible SaaS app
30+
<em> </em> | <em>push</em> push extension to extensible SaaS app
31+
<em>t</em> | <em>lint</em> run linter for env or model checks
32+
<em>v</em> | <em>version</em> get detailed version information
33+
<em> </em> | <em>completion</em> add/remove cli completion for cds commands
34+
<em>?</em> | <em>help</em> get detailed usage information
35+
36+
Learn more about each command using:
37+
<em>cds help</em> &lt;command&gt; or
38+
<em>cds</em> &lt;command&gt; <em>--help</em>
39+
</pre>

‎tools/cds-typer_help-output.md renamed to ‎tools/assets/help/cds-typer.out.md

Lines changed: 15 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<!-- this file is automatically generated and updated by a github action -->
2-
```log
3-
> @cap-js/[email protected] --help
2+
<pre class="log">
3+
> @cap-js/[email protected] cds-typer --help
44

55
SYNOPSIS
66

@@ -16,52 +16,45 @@ OPTIONS
1616

1717
This text.
1818

19-
--inlineDeclarations
20-
--inline_declarations: <flat | structured>
19+
--IEEE754Compatible: &lt;true | false&gt;
20+
(default: false)
21+
22+
If set to true, floating point properties are generated
23+
as IEEE754 compatible '(number | string)' instead of 'number'.
24+
25+
--inlineDeclarations: &lt;flat | structured&gt;
2126
(default: structured)
2227

2328
Whether to resolve inline type declarations
2429
flat: (x_a, x_b, ...)
2530
or structured: (x: {a, b}).
2631

27-
--IEEE754Compatible
28-
--ieee754compatible: <true | false>
29-
(default: false)
30-
31-
If set to true, floating point properties are generated
32-
as IEEE754 compatible '(number | string)' instead of 'number'.
33-
34-
--jsConfigPath
35-
--js_config_path: <string>
32+
--jsConfigPath: &lt;string&gt;
3633

3734
Path to where the jsconfig.json should be written.
3835
If specified, cds-typer will create a jsconfig.json file and
3936
set it up to restrict property usage in types entities to
4037
existing properties only.
4138

42-
--logLevel
43-
--log_level SILENT | ERROR | WARN | INFO | DEBUG | TRACE | SILLY | VERBOSE
39+
--logLevel SILENT | ERROR | WARN | INFO | DEBUG | TRACE | SILLY | VERBOSE
4440
(default: ERROR)
4541

4642
Minimum log level that is printed.
4743
The default is only used if no explicit value is passed
4844
and there is no configuration passed via cds.env either.
4945

50-
--outputDirectory
51-
--output_directory: <string>
46+
--outputDirectory: &lt;string&gt;
5247
(default: ./)
5348

5449
Root directory to write the generated files to.
5550

56-
--propertiesOptional
57-
--properties_optional: <true | false>
51+
--propertiesOptional: &lt;true | false&gt;
5852
(default: true)
5953

6054
If set to true, properties in entities are
6155
always generated as optional (a?: T).
6256

63-
--useEntitiesProxy
64-
--use_entities_proxy: <true | false>
57+
--useEntitiesProxy: &lt;true | false&gt;
6558
(default: false)
6659

6760
If set to true the 'cds.entities' exports in the generated 'index.js'
@@ -74,5 +67,4 @@ OPTIONS
7467
--version
7568

7669
Prints the version of this tool.
77-
78-
```
70+
</pre>

‎tools/assets/help/cds-version-md.out.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<!-- this file is automatically generated and updated by a github action -->
2+
<pre class="log">
3+
> @sap/[email protected] cds version --markdown
4+
5+
| your-project | &lt;Add your repository here&gt; |
6+
| ---------------------- | ---------------------------------------------------------------------------------------- |
7+
| @cap-js/asyncapi | 1.0.2 |
8+
| @cap-js/openapi | 1.0.5 |
9+
| @sap/cds | 8.3.0 |
10+
| @sap/cds-compiler | 5.3.0 |
11+
| @sap/cds-dk (global) | 8.4.0 |
12+
| @sap/cds-fiori | 1.2.7 |
13+
| @sap/cds-foss | 5.0.1 |
14+
| @sap/cds-mtxs | 2.1.1 |
15+
| @sap/eslint-plugin-cds | 3.0.6 |
16+
| Node.js | v22.8.0 |
17+
</pre>

‎tools/assets/help/cds-version.out.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<!-- this file is automatically generated and updated by a github action -->
2+
<pre class="log">
3+
> @sap/[email protected] cds version
4+
5+
<em>@cap-js/asyncapi</em>: 1.0.2
6+
<em>@cap-js/openapi</em>: 1.0.5
7+
<em>@sap/cds</em>: 8.3.0
8+
<em>@sap/cds-compiler</em>: 5.3.0
9+
<em>@sap/cds-dk (global)</em>: 8.4.0
10+
<em>@sap/cds-fiori</em>: 1.2.7
11+
<em>@sap/cds-foss</em>: 5.0.1
12+
<em>@sap/cds-mtxs</em>: 2.1.1
13+
<em>@sap/eslint-plugin-cds</em>: 3.0.6
14+
<em>Node.js</em>: v22.8.0
15+
<em>your-project</em>: 1.0.0
16+
</pre>

‎tools/assets/help/cds-watch.out.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<!-- this file is automatically generated and updated by a github action -->
2+
<pre class="log">
3+
> @sap/[email protected] cds watch --help
4+
5+
<strong>SYNOPSIS</strong>
6+
<em>cds watch</em> [&lt;project&gt;]
7+
8+
Tells cds to watch for relevant things to come or change in the specified
9+
project or the current work directory. Compiles and (re-)runs the server
10+
on every change detected.
11+
12+
Actually, cds watch is just a convenient shortcut for:
13+
<em>cds serve all --with-mocks --in-memory?</em>
14+
15+
<strong>OPTIONS</strong>
16+
<em>--port</em> &lt;number&gt;
17+
18+
Specify the port on which the launched server listens.
19+
If you specify '0', the server picks a random free port.
20+
Alternatively, specify the port using env variable <i>PORT</i>.
21+
22+
<em>--ext</em> &lt;extensions&gt;
23+
24+
Specify file extensions to watch for in a comma-separated list.
25+
<em>Example:</em> cds w --ext cds,json,js.
26+
27+
<em>--livereload</em> &lt;port | false&gt;
28+
29+
Specify the port for the livereload server. Defaults to '35729'.
30+
Disable it with value <i>false</i>.
31+
32+
<em>--open</em> &lt;url&gt;
33+
34+
Open the given URL (suffix) in the browser after starting.
35+
If none is given, the default application URL will be opened.
36+
37+
<em>--profile</em> &lt;profile,...&gt;
38+
39+
Specify from which profile(s) the binding information is taken.
40+
<em>Example:</em> cds w --profile hybrid,production
41+
42+
<strong>SEE ALSO</strong>
43+
<em>cds serve --help</em> for the different start options.
44+
</pre>

0 commit comments

Comments
 (0)