@@ -14,17 +14,26 @@ vi.mock("proper-lockfile", () => ({
1414} ) )
1515
1616/**
17- * The artefact spelling is caller-owned: a writer that renames the leaf as part of its own
18- * write captures the spelling once, before the first rename, and hands it back per
19- * acquisition, because re-deriving it after the rename names a different artefact for one
20- * file. The two carried fileLock specs name the `.lock` suffix but never pass or assert a
21- * spelling, so the leg in `_lockCanonicalKey` that consumes `artefactSpelling` would ship
22- * untested. These acquisitions are two-sided: dropping the caller's spelling in favour of
23- * the derived one fails the first test, and deriving nothing fails the second.
17+ * The artefact spelling is caller-owned: a writer that renames the leaf as part of its own write
18+ * captures the spelling once, before the first rename, and hands it back per acquisition, because
19+ * re-deriving it after the rename names a different artefact for one file. The two carried fileLock
20+ * specs name the `.lock` suffix but never pass or assert a spelling, so the leg in `_lockCanonicalKey`
21+ * that consumes `artefactSpelling` would ship untested. These acquisitions are two-sided: dropping
22+ * the caller's spelling in favour of the derived one fails the first test, and deriving nothing
23+ * fails the second.
24+ *
25+ * Nothing here spells a path by hand. `canonicalLockPath` canonicalizes with `fs.promises.realpath`
26+ * while `lockArtefactSpelling` canonicalizes with `fsSync.realpathSync.native`, and on the windows
27+ * runner those two routes answer with different spellings of the same directory - the profile temp
28+ * directory came back as the 8.3 short form from one and as the long form from the other, which is
29+ * what made the first version of this spec fail on platform-unit-test (windows-latest) while
30+ * passing locally. So the canonical key, the derived artefact and the parent the caller-supplied
31+ * spelling is built under are all read back from the code's own first acquisition: what stays
32+ * asserted is the behaviour - the string handed in reaches the library verbatim, both acquisitions
33+ * take the same key, and the derived artefact differs from the supplied one and repeats exactly.
2434 */
25- const dir = fsSync . realpathSync ( fsSync . mkdtempSync ( path . join ( os . tmpdir ( ) , "filelock-artefact-spelling-" ) ) )
35+ const dir = fsSync . mkdtempSync ( path . join ( os . tmpdir ( ) , "filelock-artefact-spelling-" ) )
2636const target = path . join ( dir , "task.json" )
27- const supplied = path . join ( dir , "captured-before-the-rename.json.lock" )
2837
2938fsSync . writeFileSync ( target , "{}" )
3039
@@ -36,24 +45,47 @@ beforeEach(() => {
3645 vi . mocked ( lockfile . lock ) . mockReset ( )
3746} )
3847
48+ /** One acquisition with no spelling handed in, which is where the code spells both the key and the artefact. */
49+ async function acquireOnceAndReadBack ( ) : Promise < { canonicalKey : string ; derivedArtefact : string } > {
50+ const releaseLock = await acquireFileLock ( target )
51+ const call = vi . mocked ( lockfile . lock ) . mock . calls [ 0 ]
52+ const canonicalKey = String ( call ?. [ 0 ] )
53+ const derivedArtefact = String ( call ?. [ 1 ] ?. lockfilePath )
54+ await releaseLock ( )
55+
56+ return { canonicalKey, derivedArtefact }
57+ }
58+
3959describe ( "acquireFileLock artefact spelling" , ( ) => {
4060 test ( "uses a caller-supplied spelling verbatim as the artefact" , async ( ) => {
61+ const { canonicalKey, derivedArtefact } = await acquireOnceAndReadBack ( )
62+ const supplied = path . join ( path . dirname ( canonicalKey ) , "captured-before-the-rename.json.lock" )
63+
4164 const releaseLock = await acquireFileLock ( target , { artefactSpelling : supplied } )
4265
43- expect ( lockfile . lock ) . toHaveBeenCalledTimes ( 1 )
44- expect ( lockfile . lock ) . toHaveBeenCalledWith (
45- target ,
66+ expect ( lockfile . lock ) . toHaveBeenCalledTimes ( 2 )
67+ expect ( lockfile . lock ) . toHaveBeenNthCalledWith (
68+ 2 ,
69+ // the same key the spelling-free acquisition took: one file, one key, whatever the volume spells it as
70+ canonicalKey ,
4671 expect . objectContaining ( { lockfilePath : supplied , realpath : false } ) ,
4772 )
4873
4974 await releaseLock ( )
75+
76+ expect ( derivedArtefact . endsWith ( ".lock" ) ) . toBe ( true )
77+ expect ( path . basename ( derivedArtefact ) ) . toBe ( "task.json.lock" )
78+ expect ( path . basename ( supplied ) ) . toBe ( "captured-before-the-rename.json.lock" )
79+ expect ( supplied ) . not . toBe ( derivedArtefact )
5080 } )
5181
5282 test ( "derives its own artefact when no spelling is handed in, and the two differ" , async ( ) => {
53- const derived = lockArtefactSpelling ( target )
83+ const { canonicalKey, derivedArtefact } = await acquireOnceAndReadBack ( )
84+ const supplied = path . join ( path . dirname ( canonicalKey ) , "captured-before-the-rename.json.lock" )
5485
55- expect ( derived . endsWith ( ".lock" ) ) . toBe ( true )
56- expect ( derived ) . not . toBe ( supplied )
86+ // the artefact the library was handed is the exported helper applied to the key the code locked,
87+ // which is what makes a caller-supplied spelling comparable with a derived one
88+ expect ( derivedArtefact ) . toBe ( lockArtefactSpelling ( canonicalKey ) )
5789
5890 const callerSpelled = await acquireFileLock ( target , { artefactSpelling : supplied } )
5991 await callerSpelled ( )
@@ -62,7 +94,10 @@ describe("acquireFileLock artefact spelling", () => {
6294 const derivedAgain = await acquireFileLock ( target )
6395 await derivedAgain ( )
6496
65- const artefacts = vi . mocked ( lockfile . lock ) . mock . calls . map ( ( call ) => String ( call [ 1 ] ?. lockfilePath ) )
66- expect ( artefacts ) . toEqual ( [ supplied , derived , derived ] )
97+ const artefacts = vi
98+ . mocked ( lockfile . lock )
99+ . mock . calls . slice ( 1 )
100+ . map ( ( call ) => String ( call [ 1 ] ?. lockfilePath ) )
101+ expect ( artefacts ) . toEqual ( [ supplied , derivedArtefact , derivedArtefact ] )
67102 } )
68103} )
0 commit comments