11import * as fs from "fs/promises"
22import * as os from "os"
33import * as path from "path"
4- import type { Stats } from "fs"
4+ import type { BigIntStats } from "fs"
55import { afterEach , beforeEach , describe , expect , it } from "vitest"
66
77import { computeVersionToken , versionTokenOfStat } from "../versionToken"
88
9- // Stats is a class-backed interface without a public constructor, so a plain-object
10- // test double is the only practical way to pin the token format without real files.
11- // Last-resort double assertion (test-local, per AGENTS.md).
12- function makeStats ( overrides : Partial < Stats > = { } ) : Stats {
13- const base : Partial < Stats > = {
14- dev : 7 ,
15- ino : 4242 ,
16- size : 1234 ,
17- atimeMs : 1_700_000_000_000 ,
18- mtimeMs : 1_700_000_000_123.456 ,
19- ctimeMs : 1_700_000_000_789.999 ,
20- birthtimeMs : 1_700_000_000_000 ,
9+ // BigIntStats is a class-backed interface without a public constructor, so a
10+ // plain-object test double is the only practical way to pin the token format
11+ // without real files. Last-resort double assertion (test-local, per AGENTS.md).
12+ function makeStats ( overrides : Partial < BigIntStats > = { } ) : BigIntStats {
13+ // This repo's @types/node models every StatsBase field (including the *Ms
14+ // fields) as the parameter type T, so all values here are bigint literals;
15+ // the token only reads the *Ns fields. Single-step downcast from Partial to
16+ // the full type (BigIntStats has no public constructor).
17+ const base : Partial < BigIntStats > = {
18+ dev : 7n ,
19+ ino : 4242n ,
20+ size : 1234n ,
21+ atimeMs : 1_700_000_000_000n ,
22+ mtimeMs : 1_700_000_000_123n ,
23+ ctimeMs : 1_700_000_000_789n ,
24+ birthtimeMs : 1_700_000_000_000n ,
25+ atimeNs : 1_700_000_000_000_000_000n ,
26+ mtimeNs : 1_700_000_000_123_456_789n ,
27+ ctimeNs : 1_700_000_000_789_999_999n ,
28+ birthtimeNs : 1_700_000_000_000_000_000n ,
2129 }
22- return { ...base , ...overrides } as unknown as Stats
30+ return { ...base , ...overrides } as BigIntStats
2331}
2432
2533describe ( "versionTokenOfStat (A1, epic #1375)" , ( ) => {
2634 it ( "is deterministic for an identical stat" , ( ) => {
2735 expect ( versionTokenOfStat ( makeStats ( ) ) ) . toBe ( versionTokenOfStat ( makeStats ( ) ) )
2836 } )
2937
30- it ( "matches the documented dev:ino:size:mtimeNs:ctimeNs format" , ( ) => {
31- const expected = [
32- "7" ,
33- "4242" ,
34- "1234" ,
35- Math . round ( 1_700_000_000_123.456 * 1e6 ) . toString ( ) ,
36- Math . round ( 1_700_000_000_789.999 * 1e6 ) . toString ( ) ,
37- ] . join ( ":" )
38- expect ( versionTokenOfStat ( makeStats ( ) ) ) . toBe ( expected )
38+ it ( "matches the documented dev:ino:size:mtimeNs:ctimeNs format with exact decimal fields" , ( ) => {
39+ expect ( versionTokenOfStat ( makeStats ( ) ) ) . toBe ( "7:4242:1234:1700000000123456789:1700000000789999999" )
3940 } )
4041
4142 it ( "distinguishes size changes at identical timestamps" , ( ) => {
42- expect ( versionTokenOfStat ( makeStats ( { size : 1235 } ) ) ) . not . toBe ( versionTokenOfStat ( makeStats ( ) ) )
43+ expect ( versionTokenOfStat ( makeStats ( { size : 1235n } ) ) ) . not . toBe ( versionTokenOfStat ( makeStats ( ) ) )
4344 } )
4445
45- it ( "distinguishes mtime changes at identical size" , ( ) => {
46- expect ( versionTokenOfStat ( makeStats ( { mtimeMs : 1_700_000_000_124 } ) ) ) . not . toBe ( versionTokenOfStat ( makeStats ( ) ) )
46+ it ( "distinguishes a one-nanosecond mtime change" , ( ) => {
47+ expect ( versionTokenOfStat ( makeStats ( { mtimeNs : 1_700_000_000_123_456_790n } ) ) ) . not . toBe (
48+ versionTokenOfStat ( makeStats ( ) ) ,
49+ )
4750 } )
4851
4952 it ( "distinguishes a replaced file (dev/ino change) with identical content state" , ( ) => {
50- const replaced = makeStats ( { dev : 8 , ino : 999 } )
53+ const replaced = makeStats ( { dev : 8n , ino : 999n } )
5154 expect ( versionTokenOfStat ( replaced ) ) . not . toBe ( versionTokenOfStat ( makeStats ( ) ) )
5255 } )
5356
54- it ( "preserves sub-ms mtime resolution in the ns field" , ( ) => {
55- const wholeMs = versionTokenOfStat ( makeStats ( { mtimeMs : 1_700_000_000_123 } ) )
56- const halfMsLater = versionTokenOfStat ( makeStats ( { mtimeMs : 1_700_000_000_123.5 } ) )
57- expect ( halfMsLater ) . not . toBe ( wholeMs )
58- // 0.5 ms = 500_000 ns. The float-derived ns field is quantized (~256 ns at
59- // this epoch), so allow a bounded drift instead of asserting an exact value.
60- const diff = Number ( halfMsLater . split ( ":" ) [ 3 ] ) - Number ( wholeMs . split ( ":" ) [ 3 ] )
61- expect ( Math . abs ( diff - 500_000 ) ) . toBeLessThanOrEqual ( 512 )
57+ it ( "renders nanosecond resolution exactly (no float quantization)" , ( ) => {
58+ const base = versionTokenOfStat ( makeStats ( ) )
59+ const plusOneMicrosecond = versionTokenOfStat ( makeStats ( { mtimeNs : 1_700_000_000_123_457_789n } ) )
60+ // 1_000 ns apart — the BigInt derivation must keep the delta exact.
61+ const baseNs = BigInt ( base . split ( ":" ) [ 3 ] )
62+ const microNs = BigInt ( plusOneMicrosecond . split ( ":" ) [ 3 ] )
63+ expect ( microNs - baseNs ) . toBe ( 1_000n )
6264 } )
6365
64- it ( "handles sizes beyond 32 bits without precision loss" , ( ) => {
65- const size = 5_000_000_000 // > 2^32
66+ it ( "handles sizes beyond Number.MAX_SAFE_INTEGER without precision loss" , ( ) => {
67+ const size = 10_000_000_000_000_001n // 10^16 + 1 > 2^53
6668 const token = versionTokenOfStat ( makeStats ( { size } ) )
67- expect ( token ) . toContain ( ` :4242:${ size } :`)
69+ expect ( token ) . toBe ( `7 :4242:${ size } :1700000000123456789:1700000000789999999 `)
6870 } )
6971} )
7072
@@ -82,9 +84,9 @@ describe("computeVersionToken (A1, epic #1375)", () => {
8284 await fs . rm ( tmpDir , { recursive : true , force : true } )
8385 } )
8486
85- it ( "derives the token from the on-disk state (single stat)" , async ( ) => {
87+ it ( "derives the token from the on-disk state (single bigint stat)" , async ( ) => {
8688 const token = await computeVersionToken ( file )
87- expect ( token ) . toBe ( versionTokenOfStat ( await fs . stat ( file ) ) )
89+ expect ( token ) . toBe ( versionTokenOfStat ( await fs . stat ( file , { bigint : true } ) ) )
8890 } )
8991
9092 it ( "changes when the file content changes" , async ( ) => {
0 commit comments