refactor(command step): API for parameter overrides is less opaque an…

…d just uses the raw value

Version 5.7.x and 5.8.x prefixed a given parameter override with $. This meant that the API for such
an override was quite awkward and assumed knowledge of buildkite-graph's implementation. Later
versions use the given value verbatim, assuming the env var format that Buildkite supports.

BREAKING CHANGE: `withParameterOverride` assumes a env var interpolation template to be passed (e.g.
starting with `$`)

src/__tests__/command.spec.ts

@@ -377,19 +377,27 @@ describe('buildkite-graph', () => {
       });
 
       describe('withParameterOverride', () => {
+        it('asserts that the passed override is a variable', async () => {
+          await expect(() =>
+            new CommandStep('noop').withParameterOverride(
+              'priority',
+              'MY_PRIORITY',
+            ),
+          ).toThrow();
+        });
         it('produces an override for a given key', async () => {
           await expect(
             new CommandStep('noop')
-              .withParameterOverride('priority', 'MY_PRIORITY')
+              .withParameterOverride('priority', '${MY_PRIORITY:-0}')
               .toJson(),
           ).resolves.toEqual(
-            expect.objectContaining({ priority: '$MY_PRIORITY' }),
+            expect.objectContaining({ priority: '${MY_PRIORITY:-0}' }),
           );
         });
         it('supports double escape', async () => {
           await expect(
             new CommandStep('noop')
-              .withParameterOverride('priority', '$MY_PRIORITY')
+              .withParameterOverride('priority', '$$MY_PRIORITY')
               .toJson(),
           ).resolves.toEqual(
             expect.objectContaining({ priority: '$$MY_PRIORITY' }),

src/steps/command.ts

@@ -252,14 +252,16 @@ export class CommandStep extends LabeledStep {
 
   /**
    * Allows to override the value of a property of the command.
-   * The override is the name of a environment variable.
+   * The override needs to follow the syntax for a Buildkite-supported
+   * environment variable (supporting fallbacks, etc.).
    *
-   * E.g. `withParameterOverride('priority', 'CUSTOM_PRIORITY')` would
+   * E.g. `withParameterOverride('priority', '${CUSTOM_PRIORITY}')` would
    * then yield `priority: ${CUSTOM_PRIORITY}` in the resulting serialization.
+   * The value is used verbatim.
    */
   withParameterOverride(key: CommandProperty, value: string): this {
     ow(key, ow.string.nonEmpty);
-    ow(value, ow.string.nonEmpty);
+    ow(value, ow.string.nonEmpty.startsWith('$'));
     this.overrides.set(key, value);
     return this;
   }
@@ -285,7 +287,7 @@ export class CommandStep extends LabeledStep {
 
   private valueWithOverride<T>(value: T, key: CommandProperty): string | T {
     if (this.overrides.has(key)) {
-      return ('$' + this.overrides.get(key)) as string;
+      return this.overrides.get(key) as string;
     }
     return value;
   }