Expose ParseError cause

common/changes/@microsoft/rushell/parse-error-cause_2026-08-17-20-14.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rushell",
+      "comment": "Expose a ParseError's underlying error through the standard Error.cause property while retaining innerError as an alias.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/rushell"
+}

libraries/rushell/src/ParseError.ts

@@ -19,12 +19,15 @@ export class ParseError extends Error {
   public readonly unformattedMessage: string;
 
   /**
-   * The underlying error, if this error is resulted from an earlier error.
+   * The underlying error, if this error resulted from an earlier error.
+   *
+   * @remarks
+   * This property is a backwards-compatible alias for {@link Error.cause}.
    */
   public readonly innerError: Error | undefined;
 
   public constructor(message: string, range: TextRange, innerError?: Error) {
-    super(_formatMessage(message, range));
+    super(_formatMessage(message, range), innerError === undefined ? undefined : { cause: innerError });
 
     // Boilerplate for extending a system class
     //

libraries/rushell/src/test/ParseError.test.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { ParseError } from '../ParseError';
+import { TextRange } from '../TextRange';
+
+test('omits cause when no inner error is supplied', () => {
+  const error: ParseError = new ParseError('Parse failed', TextRange.empty);
+
+  expect(error.message).toBe('Parse failed');
+  expect(error.name).toBe('Error');
+  expect(error.stack).toContain('Error: Parse failed');
+  expect(Object.hasOwn(error, 'cause')).toBe(false);
+  expect(error.cause).toBeUndefined();
+  expect(Object.getOwnPropertyDescriptor(error, 'innerError')).toEqual({
+    configurable: true,
+    enumerable: true,
+    value: undefined,
+    writable: true
+  });
+});
+
+test('exposes the inner error as the standard cause and legacy alias', () => {
+  const innerError: Error = new Error('Inner failure');
+  const error: ParseError = new ParseError('Parse failed', TextRange.empty, innerError);
+
+  expect(error.cause).toBe(innerError);
+  expect(error.innerError).toBe(innerError);
+  expect(Object.getOwnPropertyDescriptor(error, 'cause')).toEqual({
+    configurable: true,
+    enumerable: false,
+    value: innerError,
+    writable: true
+  });
+});