[🔥AUDIT🔥] Make the error messages more helpful (#1796)

🖍 _This is an audit!_ 🖍

## Summary:
This updates the thrown error messages to be more helpful by including relevant information, such as the the starting path or the marker being looked for.

Issue: Closes #1794

## Test plan:
`pnpm test`
`pnpm lint`
`pnpm typecheck`

Author: somewhatabstract

Auditors: copilot-pull-request-reviewer[bot], somewhatabstract

Required Reviewers:

Approved By:

Checks: ✅ 8 checks were successful, ⏭️  1 check has been skipped

Pull Request URL: #1796

Author: somewhatabstract

.changeset/soft-planes-lead.md

@@ -0,0 +1,5 @@
+---
+"ancesdir": major
+---
+
+Now throws more detailed errors

.github/workflows/nodejs.yml

@@ -2,8 +2,9 @@ name: Node CI
 
 on:
   pull_request:
-    branches:
-    - main
+    # ready_for_review is useful for when a PR is converted from "draft" to "not
+    # draft".
+    types: [edited, opened, synchronize, ready_for_review, reopened]
 
   push:
     branches:

jest.config.js

@@ -20,4 +20,6 @@ module.exports = {
     },
 
     setupFilesAfterEnv: ["jest-extended/all"],
+
+    prettierPath: null,
 };

src/__tests__/index.test.ts

@@ -17,7 +17,7 @@ describe("ancesdir", () => {
 
         // Assert
         expect(underTest).toThrowErrorMatchingInlineSnapshot(
-            `"From path must be absolute"`,
+            `"The starting path must be absolute, but "./path" is relative"`,
         );
     });
 
@@ -44,7 +44,7 @@ describe("ancesdir", () => {
 
         // Assert
         expect(underTest).toThrowErrorMatchingInlineSnapshot(
-            `"No such marker found from given starting location"`,
+            `"Could not find marker, "markerwewontfind", from given starting location "/Absolute/Path""`,
         );
     });
 
@@ -59,7 +59,7 @@ describe("ancesdir", () => {
 
         // Assert
         expect(underTest).toThrowErrorMatchingInlineSnapshot(
-            `"No such marker found from given starting location"`,
+            `"Could not find marker, "markerwewontfind", from given starting location "/Absolute/Path""`,
         );
     });
 

src/index.ts

@@ -3,14 +3,21 @@ import * as fs from "fs";
 
 import cache from "./cache";
 
-const Errors = {
-    MARKER_NOT_FOUND: "No such marker found from given starting location",
-    NOT_ABSOLUTE_PATH: "From path must be absolute",
-} as const;
+const throwStartingPathNotAbsoluteMessage = (from: string): never => {
+    throw new Error(
+        `The starting path must be absolute, but "${from}" is relative`,
+    );
+};
+
+const throwMarkerNotFoundMessage = (from: string, marker: string): never => {
+    throw new Error(
+        `Could not find marker, "${marker}", from given starting location "${from}"`,
+    );
+};
 
 function ancesdirImpl(from: string, marker: string): string {
     if (!path.isAbsolute(from)) {
-        throw new Error(Errors.NOT_ABSOLUTE_PATH);
+        throwStartingPathNotAbsoluteMessage(from);
     }
 
     const keys = [];
@@ -31,6 +38,15 @@ function ancesdirImpl(from: string, marker: string): string {
 
         /**
          * If we have already looked this up, we can just grab it from our map!
+         *
+         * NOTE: If the marker was created after we cached the result, we will
+         * still claim it cannot be found. Equally, if the marker was deleted
+         * after we cached the result, we will still claim it was found.
+         * The assumption is that a use of ancesdir is short-lived and such
+         * scenarios aren't likely to occur. We could mitigate this by adding
+         * the ability to clear the cache, or by making the cache invalidate
+         * after a certain time period. Something to consider for a future
+         * update, though no one has asked for it yet.
          */
         const cachedResult = cache.get(key);
         if (cachedResult != null) {
@@ -39,7 +55,7 @@ function ancesdirImpl(from: string, marker: string): string {
         } else if (cache.has(key)) {
             // A null in the cache means we tried this lookup and never found
             // the marker.
-            throw new Error(Errors.MARKER_NOT_FOUND);
+            throwMarkerNotFoundMessage(from, marker);
         }
 
         /**
@@ -54,7 +70,7 @@ function ancesdirImpl(from: string, marker: string): string {
             for (const key of keys) {
                 cache.set(key, null);
             }
-            throw new Error(Errors.MARKER_NOT_FOUND);
+            throwMarkerNotFoundMessage(from, marker);
         }
 
         /**