Merge branch 'master' into no-envars

Author: 0x2b3bfa0

bin/cml.js

@@ -10,24 +10,7 @@ const yargs = require('yargs');
 const CML = require('../src/cml').default;
 const { jitsuEventPayload, send } = require('../src/analytics');
 
-const setupOpts = (opts) => {
-  const legacyEnvironmentVariables = {
-    TB_CREDENTIALS: 'CML_TENSORBOARD_DEV_CREDENTIALS',
-    DOCKER_MACHINE: 'CML_RUNNER_DOCKER_MACHINE',
-    RUNNER_IDLE_TIMEOUT: 'CML_RUNNER_IDLE_TIMEOUT',
-    RUNNER_LABELS: 'CML_RUNNER_LABELS',
-    RUNNER_SINGLE: 'CML_RUNNER_SINGLE',
-    RUNNER_REUSE: 'CML_RUNNER_REUSE',
-    RUNNER_NO_RETRY: 'CML_RUNNER_NO_RETRY',
-    RUNNER_DRIVER: 'CML_RUNNER_DRIVER',
-    RUNNER_REPO: 'CML_RUNNER_REPO',
-    RUNNER_PATH: 'CML_RUNNER_PATH'
-  };
-
-  for (const [oldName, newName] of Object.entries(legacyEnvironmentVariables)) {
-    if (process.env[oldName]) process.env[newName] = process.env[oldName];
-  }
-
+const aliasLegacyEnvironmentVariables = () => {
   const legacyEnvironmentPrefixes = {
     CML_CI: 'CML_REPO',
     CML_PUBLISH: 'CML_ASSET',
@@ -46,6 +29,25 @@ const setupOpts = (opts) => {
     }
   }
 
+  const legacyEnvironmentVariables = {
+    TB_CREDENTIALS: 'CML_TENSORBOARD_CREDENTIALS',
+    DOCKER_MACHINE: 'CML_RUNNER_DOCKER_MACHINE',
+    RUNNER_IDLE_TIMEOUT: 'CML_RUNNER_IDLE_TIMEOUT',
+    RUNNER_LABELS: 'CML_RUNNER_LABELS',
+    RUNNER_SINGLE: 'CML_RUNNER_SINGLE',
+    RUNNER_REUSE: 'CML_RUNNER_REUSE',
+    RUNNER_NO_RETRY: 'CML_RUNNER_NO_RETRY',
+    RUNNER_DRIVER: 'CML_RUNNER_DRIVER',
+    RUNNER_REPO: 'CML_RUNNER_REPO',
+    RUNNER_PATH: 'CML_RUNNER_PATH'
+  };
+
+  for (const [oldName, newName] of Object.entries(legacyEnvironmentVariables)) {
+    if (process.env[oldName]) process.env[newName] = process.env[oldName];
+  }
+};
+
+const setupOpts = (opts) => {
   const { markdownfile } = opts;
   opts.markdownFile = markdownfile;
   opts.cml = new CML(opts);
@@ -117,6 +119,7 @@ const handleError = (message, error) => {
 };
 
 (async () => {
+  aliasLegacyEnvironmentVariables();
   setupLogger({ log: 'debug' });
 
   try {

bin/cml.test.js

@@ -1,4 +1,5 @@
 const { exec } = require('../src/utils');
+const fetch = require('node-fetch');
 
 describe('command-line interface tests', () => {
   test('cml --help', async () => {
@@ -31,3 +32,21 @@ describe('command-line interface tests', () => {
     `);
   });
 });
+
+describe('Valid Docs URLs', () => {
+  test.each([
+    'workflow/rerun',
+    'tensorboard/connect',
+    'runner/launch',
+    'repo/prepare',
+    'pr/create',
+    'comment/create',
+    'comment/update',
+    'check/create',
+    'asset/publish'
+  ])('Check Docs Link', async (cmd) => {
+    const { DOCSURL } = require(`./cml/${cmd}`);
+    const { status } = await fetch(DOCSURL);
+    expect(status).toBe(200);
+  });
+});

bin/cml/asset/publish.js

@@ -4,8 +4,11 @@ const winston = require('winston');
 
 const { CML } = require('../../../src/cml');
 
+const DESCRIPTION = 'Publish an asset';
+const DOCSURL = 'https://cml.dev/doc/usage#cml-reports';
+
 exports.command = 'publish <asset>';
-exports.description = 'Publish an asset';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   if (opts.gitlabUploads) {
@@ -56,6 +59,7 @@ exports.options = kebabcaseKeys({
   rmWatermark: {
     type: 'boolean',
     description: 'Avoid CML watermark.',
+    hidden: true,
     telemetryData: 'name'
   },
   mimeType: {
@@ -76,3 +80,4 @@ exports.options = kebabcaseKeys({
       'Specifies the repo to be used. If not specified is extracted from the CI ENV.'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/asset/publish.test.js

@@ -20,12 +20,11 @@ describe('CML cli test', () => {
             --help    Show help                                              [boolean]
 
       Options:
-            --md            Output in markdown format [title || name](url)   [boolean]
-        -t, --title         Markdown title [title](url) or ![](url title)     [string]
-            --native        Uses driver's native capabilities to upload assets instead
-                            of CML's storage; not available on GitHub        [boolean]
-            --rm-watermark  Avoid CML watermark.                             [boolean]
-            --mime-type     MIME type [string] [default: infer from the file contents]"
+            --md         Output in markdown format [title || name](url)      [boolean]
+        -t, --title      Markdown title [title](url) or ![](url title)        [string]
+            --native     Uses driver's native capabilities to upload assets instead of
+                         CML's storage; not available on GitHub              [boolean]
+            --mime-type  MIME type    [string] [default: infer from the file contents]"
     `);
   });
 });

bin/cml/check/create.js

@@ -1,8 +1,11 @@
 const fs = require('fs').promises;
 const kebabcaseKeys = require('kebabcase-keys');
 
+const DESCRIPTION = 'Create a check report';
+const DOCSURL = 'https://cml.dev/doc/ref/check';
+
 exports.command = 'create <markdown file>';
-exports.description = 'Create a check report';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml, markdownfile } = opts;
@@ -53,3 +56,4 @@ exports.options = kebabcaseKeys({
     description: 'Title of the check'
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/comment/create.js

@@ -1,7 +1,10 @@
 const kebabcaseKeys = require('kebabcase-keys');
 
+const DESCRIPTION = 'Create a comment';
+const DOCSURL = 'https://cml.dev/doc/ref/comment#create';
+
 exports.command = 'create <markdown file>';
-exports.description = 'Create a comment';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml } = opts;
@@ -63,6 +66,15 @@ exports.options = kebabcaseKeys({
     type: 'boolean',
     description:
       'Avoid watermark; CML needs a watermark to be able to distinguish CML comments from others',
+    hidden: true,
     telemetryData: 'name'
+  },
+  watermarkTitle: {
+    type: 'string',
+    description:
+      'Hidden comment marker (used for targeting in subsequent `cml comment update`); "{workflow}" & "{run}" are auto-replaced',
+    default: '',
+    conflicts: ['rmWatermark']
   }
 });
+exports.DOCSURL = DOCSURL;

bin/cml/comment/create.test.js

@@ -3,7 +3,6 @@ const { exec } = require('../../../src/utils');
 describe('Comment integration tests', () => {
   test('cml send-comment --help', async () => {
     const output = await exec(`node ./bin/cml.js send-comment --help`);
-
     expect(output).toMatchInlineSnapshot(`
       "cml.js send-comment <markdown file>
 
@@ -31,8 +30,9 @@ describe('Comment integration tests', () => {
         --publish-native, --native  Uses driver's native capabilities to upload assets
                                     instead of CML's storage; not available on GitHub
                                                                              [boolean]
-        --rm-watermark              Avoid watermark; CML needs a watermark to be able
-                                    to distinguish CML comments from others  [boolean]"
+        --watermark-title           Hidden comment marker (used for targeting in
+                                    subsequent \`cml comment update\`); \\"{workflow}\\" &
+                                    \\"{run}\\" are auto-replaced   [string] [default: \\"\\"]"
     `);
   });
 });

bin/cml/comment/update.js

@@ -1,10 +1,14 @@
 const { builder, handler } = require('./create');
 
+const DESCRIPTION = 'Update a comment';
+const DOCSURL = 'https://cml.dev/doc/ref/comment#update';
+
 exports.command = 'update <markdown file>';
-exports.description = 'Update a comment';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   await handler({ ...opts, update: true });
 };
 
 exports.builder = builder;
+exports.DOCSURL = DOCSURL;

bin/cml/pr/create.e2e.test.js

@@ -12,6 +12,7 @@ describe('CML e2e', () => {
       Commands:
         cml.js pr create <glob path...>  Create a pull request with the specified
                                          files
+                                         https://cml.dev/doc/ref/pr
 
       Global Options:
         --log     Logging verbosity

bin/cml/pr/create.js

@@ -6,8 +6,11 @@ const {
   GIT_USER_EMAIL
 } = require('../../../src/cml');
 
+const DESCRIPTION = 'Create a pull request with the specified files';
+const DOCSURL = 'https://cml.dev/doc/ref/pr';
+
 exports.command = 'create <glob path...>';
-exports.description = 'Create a pull request with the specified files';
+exports.description = `${DESCRIPTION}\n${DOCSURL}`;
 
 exports.handler = async (opts) => {
   const { cml, globpath: globs } = opts;
@@ -78,3 +81,4 @@ exports.options = kebabcaseKeys({
     description: 'Git user name'
   }
 });
+exports.DOCSURL = DOCSURL;