Skip to content

Commit ec138c5

Browse files
kanadguptakanadgupta
authored
feat(logger): improved warnings for GHA users (#1290)
| 🚥 Resolves RM-13246 | | :------------------- | ## 🧰 Changes updates the formatting for our `this.warn()` statements so they're surfaced properly in github actions annotations. - [x] make sure everything else is merged in and refresh this branch afterwards - [x] do a dry run with the CI changes in #1284 to ensure that warnings are surfaced properly ## 🧬 QA & Testing i confirmed that these are showing up properly: https://github.com/readmeio/rdme/actions/runs/16131074838/job/45518517159
1 parent 319674f commit ec138c5

File tree

9 files changed

+60
-60
lines changed

9 files changed

+60
-60
lines changed

‎__tests__/commands/changelog/__snapshots__/upload.test.ts.snap‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -343,12 +343,11 @@ exports[`rdme changelog upload > given that the file path is a single file > and
343343
],
344344
"updated": [],
345345
},
346-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
347-
› Use at your own risk!
348-
- 🔬 Validating frontmatter data...
346+
"stderr": "- 🔬 Validating frontmatter data...
349347
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
350348
",
351-
"stdout": "Automatically fixing issues in 1 file(s)...
349+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
350+
Automatically fixing issues in 1 file(s)...
352351
=== BEGIN writeFileSync to file: __tests__/__fixtures__/changelog/legacy-docs/autofixable.md ===
353352
---
354353
type: added
@@ -383,14 +382,13 @@ exports[`rdme changelog upload > given that the file path is a single file > and
383382
"skipped": [],
384383
"updated": [],
385384
},
386-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
387-
› Use at your own risk!
388-
- 🔬 Validating frontmatter data...
385+
"stderr": "- 🔬 Validating frontmatter data...
389386
✔ 🔬 Validating frontmatter data... no issues found!
390387
- 🚀 Uploading files to ReadMe...
391388
✔ 🚀 Uploading files to ReadMe... done!
392389
",
393-
"stdout": "🌱 Successfully created 1 page(s) in ReadMe:
390+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
391+
🌱 Successfully created 1 page(s) in ReadMe:
394392
- new-doc (__tests__/__fixtures__/changelog/new-docs/new-doc.md)
395393
",
396394
}
@@ -399,12 +397,11 @@ exports[`rdme changelog upload > given that the file path is a single file > and
399397
exports[`rdme changelog upload > given that the file path is a single file > and the command is being run in a CI environment > should error out if the file has validation errors 1`] = `
400398
{
401399
"error": [Error: 1 file(s) have issues that should be fixed before uploading to ReadMe. Please run \`rdme changelog upload __tests__/__fixtures__/changelog/legacy-docs/autofixable.md --dry-run\` in a non-CI environment to fix them.],
402-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
403-
› Use at your own risk!
404-
- 🔬 Validating frontmatter data...
400+
"stderr": "- 🔬 Validating frontmatter data...
405401
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
406402
",
407-
"stdout": "",
403+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
404+
",
408405
}
409406
`;
410407

‎__tests__/commands/custompages/__snapshots__/upload.test.ts.snap‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -360,12 +360,11 @@ exports[`custompages upload > given that the file path is a single file > and th
360360
],
361361
"updated": [],
362362
},
363-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
364-
› Use at your own risk!
365-
- 🔬 Validating frontmatter data...
363+
"stderr": "- 🔬 Validating frontmatter data...
366364
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
367365
",
368-
"stdout": "Automatically fixing issues in 1 file(s)...
366+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
367+
Automatically fixing issues in 1 file(s)...
369368
=== BEGIN writeFileSync to file: __tests__/__fixtures__/custompages/mixed-docs/legacy-page.md ===
370369
---
371370
title: This is the document title
@@ -401,14 +400,13 @@ exports[`custompages upload > given that the file path is a single file > and th
401400
"skipped": [],
402401
"updated": [],
403402
},
404-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
405-
› Use at your own risk!
406-
- 🔬 Validating frontmatter data...
403+
"stderr": "- 🔬 Validating frontmatter data...
407404
✔ 🔬 Validating frontmatter data... no issues found!
408405
- 🚀 Uploading files to ReadMe...
409406
✔ 🚀 Uploading files to ReadMe... done!
410407
",
411-
"stdout": "🌱 Successfully created 1 page(s) in ReadMe:
408+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
409+
🌱 Successfully created 1 page(s) in ReadMe:
412410
- new-doc (__tests__/__fixtures__/custompages/new-docs/new-doc.md)
413411
",
414412
}
@@ -417,12 +415,11 @@ exports[`custompages upload > given that the file path is a single file > and th
417415
exports[`custompages upload > given that the file path is a single file > and the command is being run in a CI environment > should error out if the file has validation errors 1`] = `
418416
{
419417
"error": [Error: 1 file(s) have issues that should be fixed before uploading to ReadMe. Please run \`rdme custompages upload __tests__/__fixtures__/custompages/mixed-docs/legacy-page.md --dry-run\` in a non-CI environment to fix them.],
420-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
421-
› Use at your own risk!
422-
- 🔬 Validating frontmatter data...
418+
"stderr": "- 🔬 Validating frontmatter data...
423419
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
424420
",
425-
"stdout": "",
421+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
422+
",
426423
}
427424
`;
428425

‎__tests__/commands/openapi/__snapshots__/convert.test.ts.snap‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ exports[`rdme openapi convert > error handling > should warn if given an OpenAPI
44
{
55
"result": "Your API definition has been converted and bundled and saved to output.json!",
66
"stderr": "- Validating the API definition located at petstore.json...
7-
⚠️ Warning! The input file is already OpenAPI, so no conversion is necessary. Any external references will be bundled.
7+
› Warning: The input file is already OpenAPI, so no conversion is necessary.
8+
› Any external references will be bundled.
89
",
910
"stdout": "",
1011
}
@@ -14,7 +15,8 @@ exports[`rdme openapi convert > error handling > should warn if given an OpenAPI
1415
{
1516
"result": "Your API definition has been converted and bundled and saved to output.json!",
1617
"stderr": "- Validating the API definition located at petstore.yaml...
17-
⚠️ Warning! The input file is already OpenAPI, so no conversion is necessary. Any external references will be bundled.
18+
› Warning: The input file is already OpenAPI, so no conversion is necessary.
19+
› Any external references will be bundled.
1820
",
1921
"stdout": "",
2022
}

‎__tests__/commands/openapi/__snapshots__/upload.test.ts.snap‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -141,14 +141,11 @@ exports[`rdme openapi upload > given that the API definition is a local file > a
141141
"uri": "/branches/1.0.0/apis/__tests____fixtures__petstore-simple-weird-version.json",
142142
},
143143
"stderr": "- Validating the API definition located at __tests__/__fixtures__/petstore-simple-weird-version.json...
144-
› Warning: The slug of your API Definition will be set to
145-
› __tests____fixtures__petstore-simple-weird-version.json in ReadMe. This
146-
› slug is not visible to your end users. To set this slug to something else,
147-
› use the \`--slug\` flag.
148144
- Updating your API definition to ReadMe...
149145
✔ Updating your API definition to ReadMe... done!
150146
",
151-
"stdout": "🚀 Your API definition (__tests____fixtures__petstore-simple-weird-version.json) was successfully updated in ReadMe!
147+
"stdout": "::warning::The slug of your API Definition will be set to __tests____fixtures__petstore-simple-weird-version.json in ReadMe. This slug is not visible to your end users. To set this slug to something else, use the \`--slug\` flag.
148+
🚀 Your API definition (__tests____fixtures__petstore-simple-weird-version.json) was successfully updated in ReadMe!
152149
",
153150
}
154151
`;

‎__tests__/commands/pages/__snapshots__/upload.test.ts.snap‎

Lines changed: 18 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -398,12 +398,11 @@ exports[`rdme docs upload > given that the file path is a single file > and the
398398
],
399399
"updated": [],
400400
},
401-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
402-
› Use at your own risk!
403-
- 🔬 Validating frontmatter data...
401+
"stderr": "- 🔬 Validating frontmatter data...
404402
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
405403
",
406-
"stdout": "Automatically fixing issues in 1 file(s)...
404+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
405+
Automatically fixing issues in 1 file(s)...
407406
=== BEGIN writeFileSync to file: __tests__/__fixtures__/docs/mixed-docs/legacy-category.md ===
408407
---
409408
category:
@@ -437,14 +436,13 @@ exports[`rdme docs upload > given that the file path is a single file > and the
437436
"skipped": [],
438437
"updated": [],
439438
},
440-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
441-
› Use at your own risk!
442-
- 🔬 Validating frontmatter data...
439+
"stderr": "- 🔬 Validating frontmatter data...
443440
✔ 🔬 Validating frontmatter data... no issues found!
444441
- 🚀 Uploading files to ReadMe...
445442
✔ 🚀 Uploading files to ReadMe... done!
446443
",
447-
"stdout": "🌱 Successfully created 1 page(s) in ReadMe:
444+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
445+
🌱 Successfully created 1 page(s) in ReadMe:
448446
- new-doc (__tests__/__fixtures__/docs/new-docs/new-doc.md)
449447
",
450448
}
@@ -453,12 +451,11 @@ exports[`rdme docs upload > given that the file path is a single file > and the
453451
exports[`rdme docs upload > given that the file path is a single file > and the command is being run in a CI environment > should error out if the file has validation errors 1`] = `
454452
{
455453
"error": [Error: 1 file(s) have issues that should be fixed before uploading to ReadMe. Please run \`rdme docs upload __tests__/__fixtures__/docs/mixed-docs/legacy-category.md --dry-run\` in a non-CI environment to fix them.],
456-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
457-
› Use at your own risk!
458-
- 🔬 Validating frontmatter data...
454+
"stderr": "- 🔬 Validating frontmatter data...
459455
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
460456
",
461-
"stdout": "",
457+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
458+
",
462459
}
463460
`;
464461
@@ -1336,12 +1333,11 @@ exports[`rdme reference upload > given that the file path is a single file > and
13361333
],
13371334
"updated": [],
13381335
},
1339-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
1340-
› Use at your own risk!
1341-
- 🔬 Validating frontmatter data...
1336+
"stderr": "- 🔬 Validating frontmatter data...
13421337
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
13431338
",
1344-
"stdout": "Automatically fixing issues in 1 file(s)...
1339+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
1340+
Automatically fixing issues in 1 file(s)...
13451341
=== BEGIN writeFileSync to file: __tests__/__fixtures__/docs/mixed-docs/legacy-category.md ===
13461342
---
13471343
category:
@@ -1375,14 +1371,13 @@ exports[`rdme reference upload > given that the file path is a single file > and
13751371
"skipped": [],
13761372
"updated": [],
13771373
},
1378-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
1379-
› Use at your own risk!
1380-
- 🔬 Validating frontmatter data...
1374+
"stderr": "- 🔬 Validating frontmatter data...
13811375
✔ 🔬 Validating frontmatter data... no issues found!
13821376
- 🚀 Uploading files to ReadMe...
13831377
✔ 🚀 Uploading files to ReadMe... done!
13841378
",
1385-
"stdout": "🌱 Successfully created 1 page(s) in ReadMe:
1379+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
1380+
🌱 Successfully created 1 page(s) in ReadMe:
13861381
- new-doc (__tests__/__fixtures__/docs/new-docs/new-doc.md)
13871382
",
13881383
}
@@ -1391,12 +1386,11 @@ exports[`rdme reference upload > given that the file path is a single file > and
13911386
exports[`rdme reference upload > given that the file path is a single file > and the command is being run in a CI environment > should error out if the file has validation errors 1`] = `
13921387
{
13931388
"error": [Error: 1 file(s) have issues that should be fixed before uploading to ReadMe. Please run \`rdme reference upload __tests__/__fixtures__/docs/mixed-docs/legacy-category.md --dry-run\` in a non-CI environment to fix them.],
1394-
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
1395-
› Use at your own risk!
1396-
- 🔬 Validating frontmatter data...
1389+
"stderr": "- 🔬 Validating frontmatter data...
13971390
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
13981391
",
1399-
"stdout": "",
1392+
"stdout": "::warning::This command is in an experimental alpha and is likely to change. Use at your own risk!
1393+
",
14001394
}
14011395
`;
14021396

‎src/commands/openapi/convert.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ import prompts from 'prompts';
99

1010
import BaseCommand from '../../lib/baseCommand.js';
1111
import { specArg, titleFlag, workingDirectoryFlag } from '../../lib/flags.js';
12-
import { warn } from '../../lib/logger.js';
1312
import prepareOas from '../../lib/prepareOas.js';
1413
import promptTerminal from '../../lib/promptWrapper.js';
1514
import { validateFilePath } from '../../lib/validatePromptInput.js';
@@ -59,7 +58,7 @@ export default class OpenAPIConvertCommand extends BaseCommand<typeof OpenAPICon
5958
const parsedPreparedSpec: OASDocument = JSON.parse(preparedSpec);
6059

6160
if (specType === 'OpenAPI') {
62-
warn(
61+
this.warn(
6362
'The input file is already OpenAPI, so no conversion is necessary. Any external references will be bundled.',
6463
);
6564
}

‎src/lib/baseCommand.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import type { Config, Hook, Interfaces } from '@oclif/core';
44
import { format } from 'node:util';
55

66
import * as core from '@actions/core';
7-
import { Command as OclifCommand } from '@oclif/core';
7+
import { Errors, Command as OclifCommand } from '@oclif/core';
88
import chalk from 'chalk';
99
import debugPkg from 'debug';
1010

@@ -59,6 +59,17 @@ export default abstract class BaseCommand<T extends typeof OclifCommand> extends
5959
}
6060
}
6161

62+
public warn(input: Error | string): Error | string {
63+
if (!this.jsonEnabled()) {
64+
if (isGHA()) {
65+
core.warning(input);
66+
} else {
67+
Errors.warn(input);
68+
}
69+
}
70+
return input;
71+
}
72+
6273
protected async catch(err: Error & { exitCode?: number }) {
6374
if (isTest()) {
6475
return super.catch(err);

‎src/lib/logger.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@ function error(input: string) {
3737

3838
/**
3939
* Wrapper for info/notice statements.
40-
40+
*
41+
* @deprecated use the base command's `this.info` method instead.
4142
*/
4243
function info(
4344
input: string,
@@ -65,6 +66,8 @@ function oraOptions() {
6566

6667
/**
6768
* Wrapper for warn statements.
69+
*
70+
* @deprecated use the base command's `this.warn` method instead.
6871
*/
6972
function warn(
7073
/**

‎src/lib/readmeAPIFetch.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -317,7 +317,7 @@ export async function readmeAPIv2Fetch<T extends Hook.Context = Hook.Context>(
317317
this.debug(`received warning header: ${warningHeader}`);
318318
const warnings = parseWarningHeader(warningHeader);
319319
warnings.forEach(warning => {
320-
warn(warning.message, 'ReadMe API Warning:');
320+
this.warn(`⚠️ ReadMe API Warning: ${warning.message}`);
321321
});
322322
}
323323
return res;

0 commit comments

Comments
 (0)