test-fns 1.15.5 → 1.15.6

package/dist/infra/isomorph.fs/findsertSymlink.d.ts

@@ -1,10 +1,25 @@
+/**
+ * .what = result of findsertSymlink operation
+ * .why = observability into which code path was taken for tests and debug
+ */
+export interface FindsertSymlinkResult {
+    /** whether the symlink was created or already found */
+    effect: 'created' | 'found';
+    /** race condition that was overcome, if any */
+    overcame: 'EEXIST' | 'ENOENT' | null;
+}
 /**
  * .what = creates a symlink if absent, no-op if correct symlink exists
  * .why = idempotent symlink creation safe for parallel workers
  *
+ * .note = handles three race scenarios:
+ *   1. EEXIST: another worker created symlink → verify target, return if correct
+ *   2. ENOENT on verify: another worker deleted symlink → retry
+ *   3. stale symlink/file: remove and create
+ *
  * @throws UnexpectedCodePathError if path exists but is not the expected symlink
  */
 export declare const findsertSymlink: (input: {
     target: string;
     path: string;
-}) => void;
+}) => FindsertSymlinkResult;

package/dist/infra/isomorph.fs/findsertSymlink.js

@@ -31,50 +31,78 @@ const isSymlinkEexistError_1 = require("./isSymlinkEexistError");
  * .what = creates a symlink if absent, no-op if correct symlink exists
  * .why = idempotent symlink creation safe for parallel workers
  *
+ * .note = handles three race scenarios:
+ *   1. EEXIST: another worker created symlink → verify target, return if correct
+ *   2. ENOENT on verify: another worker deleted symlink → retry
+ *   3. stale symlink/file: remove and create
+ *
  * @throws UnexpectedCodePathError if path exists but is not the expected symlink
  */
 const findsertSymlink = (input) => {
-    // check if correct symlink already exists
-    const stat = (() => {
-        try {
-            return fs.lstatSync(input.path);
+    const MAX_RETRIES = 3;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        // check if correct symlink already exists
+        const stat = (() => {
+            try {
+                return fs.lstatSync(input.path);
+            }
+            catch {
+                return null;
+            }
+        })();
+        if (stat?.isSymbolicLink()) {
+            try {
+                const currentTarget = fs.readlinkSync(input.path);
+                if (currentTarget === input.target) {
+                    return { effect: 'found', overcame: null }; // correct symlink exists
+                }
+            }
+            catch (error) {
+                // symlink deleted between lstat and readlink — retry
+                const code = error.code;
+                if (code === 'ENOENT')
+                    continue;
+                throw error;
+            }
         }
-        catch {
-            return null;
+        // remove stale symlink, directory, or file
+        if (stat) {
+            fs.rmSync(input.path, { recursive: true, force: true });
         }
-    })();
-    if (stat?.isSymbolicLink()) {
-        const currentTarget = fs.readlinkSync(input.path);
-        if (currentTarget === input.target) {
-            return; // correct symlink exists
+        // create symlink
+        try {
+            fs.symlinkSync(input.target, input.path);
+            return { effect: 'created', overcame: null }; // success
         }
-    }
-    // remove stale symlink, directory, or file
-    if (stat) {
-        fs.rmSync(input.path, { recursive: true, force: true });
-    }
-    // create symlink
-    try {
-        fs.symlinkSync(input.target, input.path);
-    }
-    catch (error) {
-        // handle race: another worker created symlink between our check and create
-        if (!(0, isSymlinkEexistError_1.isSymlinkEexistError)(error))
-            throw error;
-        // another worker created symlink — verify it's correct
-        const raceStat = fs.lstatSync(input.path);
-        if (raceStat.isSymbolicLink()) {
-            const currentTarget = fs.readlinkSync(input.path);
-            if (currentTarget === input.target) {
-                return; // correct symlink created by another worker
+        catch (error) {
+            // handle race: another worker created symlink between our check and create
+            if (!(0, isSymlinkEexistError_1.isSymlinkEexistError)(error))
+                throw error;
+            // another worker created symlink — verify it's correct
+            try {
+                const raceStat = fs.lstatSync(input.path);
+                if (raceStat.isSymbolicLink()) {
+                    const currentTarget = fs.readlinkSync(input.path);
+                    if (currentTarget === input.target) {
+                        return { effect: 'found', overcame: 'EEXIST' }; // correct symlink created by another worker
+                    }
+                }
+                throw new helpful_errors_1.UnexpectedCodePathError('symlink exists but points to unexpected target', {
+                    target: input.target,
+                    path: input.path,
+                    isSymlink: raceStat.isSymbolicLink(),
+                });
+            }
+            catch (verifyError) {
+                // symlink deleted between EEXIST and verify — retry
+                const code = verifyError.code;
+                if (code === 'ENOENT')
+                    continue;
+                throw verifyError;
             }
         }
-        throw new helpful_errors_1.UnexpectedCodePathError('symlink exists but points to unexpected target', {
-            target: input.target,
-            path: input.path,
-            isSymlink: raceStat.isSymbolicLink(),
-        });
     }
+    throw new helpful_errors_1.UnexpectedCodePathError('findsertSymlink exceeded max retries due to concurrent deletes', { target: input.target, path: input.path, maxRetries: MAX_RETRIES });
 };
 exports.findsertSymlink = findsertSymlink;
 //# sourceMappingURL=findsertSymlink.js.map

package/dist/infra/isomorph.fs/findsertSymlink.js.map

@@ -1 +1 @@
-{"version":3,"file":"findsertSymlink.js","sourceRoot":"","sources":["../../../src/infra/isomorph.fs/findsertSymlink.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,mDAAyD;AAEzD,4CAA8B;AAC9B,iEAA8D;AAE9D;;;;;GAKG;AACI,MAAM,eAAe,GAAG,CAAC,KAG/B,EAAQ,EAAE;IACT,0CAA0C;IAC1C,MAAM,IAAI,GAAG,CAAC,GAAG,EAAE;QACjB,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAEL,IAAI,IAAI,EAAE,cAAc,EAAE,EAAE,CAAC;QAC3B,MAAM,aAAa,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,aAAa,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;YACnC,OAAO,CAAC,yBAAyB;QACnC,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,IAAI,IAAI,EAAE,CAAC;QACT,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,iBAAiB;IACjB,IAAI,CAAC;QACH,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,2EAA2E;QAC3E,IAAI,CAAC,IAAA,2CAAoB,EAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QAE9C,uDAAuD;QACvD,MAAM,QAAQ,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,QAAQ,CAAC,cAAc,EAAE,EAAE,CAAC;YAC9B,MAAM,aAAa,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAClD,IAAI,aAAa,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;gBACnC,OAAO,CAAC,4CAA4C;YACtD,CAAC;QACH,CAAC;QAED,MAAM,IAAI,wCAAuB,CAC/B,gDAAgD,EAChD;YACE,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,QAAQ,CAAC,cAAc,EAAE;SACrC,CACF,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAlDW,QAAA,eAAe,mBAkD1B"}
+{"version":3,"file":"findsertSymlink.js","sourceRoot":"","sources":["../../../src/infra/isomorph.fs/findsertSymlink.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "test-fns",
   "author": "ehmpathy",
   "description": "write usecase driven tests systematically for simpler, safer, and more readable code",
-  "version": "1.15.5",
+  "version": "1.15.6",
   "repository": "ehmpathy/test-fns",
   "homepage": "https://github.com/ehmpathy/test-fns",
   "keywords": [
@@ -68,7 +68,7 @@
     "preversion": "npm run prepush",
     "postversion": "git push origin HEAD --tags --no-verify",
     "prepare:husky": "husky install && chmod ug+x .husky/*",
-    "prepare:rhachet": "rhachet init --hooks --roles behaver driver mechanic reviewer",
+    "prepare:rhachet": "rhachet init --hooks --roles mechanic behaver driver reviewer librarian ergonomist architect",
     "prepare": "if [ -e .git ] && [ -z $CI ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
     "upgrade:rhachet": "rhachet upgrade"
   },
@@ -99,11 +99,11 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.35.3",
+    "rhachet": "1.37.15",
     "rhachet-brains-anthropic": "0.3.3",
-    "rhachet-roles-bhrain": "0.12.4",
-    "rhachet-roles-bhuild": "0.10.0",
-    "rhachet-roles-ehmpathy": "1.26.3",
+    "rhachet-roles-bhrain": "0.19.0",
+    "rhachet-roles-bhuild": "0.14.1",
+    "rhachet-roles-ehmpathy": "1.27.13",
     "tsc-alias": "1.8.10",
     "tsx": "4.21.0",
     "typescript": "5.4.5",