fix: preserve BigInt precision above Number.MAX_SAFE_INTEGER

[avoidwork]

Summary

Fixes BigInt precision loss in filesize(). When a bigint above Number.MAX_SAFE_INTEGER (2^53 - 1) was passed, Number(arg) coercion silently dropped precision — filesize(BigInt(2 ** 53 + 1)) returned the same result as filesize(BigInt(2 ** 53)). Adds a dedicated BigInt branch that computes the unit exponent and value using bigint arithmetic, preserving precision and detecting unit boundaries accurately.

Type of Change

• Bug fix (non-breaking change which fixes an issue)

Related Issues

Closes #354

Testing

• Added 12 regression tests covering:
  • Precision preservation above 2^53 (2^53 vs 2^53+1 produce distinct results)
  • SI and IEC unit boundary detection
  • Exponent clamping (forced exponent below -1 and above 8)
  • BigInt bits auto-increment
  • String exponent coercion for BigInt
• npm test passes: 267 tests, 0 failures
• npm run coverage: 100% statement, branch, function, and line coverage
• npm run build succeeds

Checklist

• npm test passes
• npm run build succeeds
• 100% test coverage maintained
• No hardcoded secrets or credentials introduced
• Zero external dependencies added
• ES Modules only (no CommonJS in src/)
• JSDoc comments added/updated
• CHANGELOG.md updated (if applicable)

Screenshots (if applicable)

N/A

[avoidwork]

Audit Results — fix-bigint-precision

Goal fulfillment: All 4 goals met.

1. Preserve BigInt precision above Number.MAX_SAFE_INTEGER — ✅ filesize(2n ** 53n + 1n, {round: 15}) now differs from filesize(2n ** 53n, {round: 15}). The +1 is no longer dropped.
2. Correct unit boundary detection for BigInt — ✅ SI and IEC boundaries detected via bigint comparisons. 10^24 - 10^21 reports ZB (exponent 7); 1024^8 - 1024^7 reports ZiB (exponent 7).
3. Rejoin the common output path — ✅ The BigInt branch computes value and e, then flows into applyRounding, applyPrecisionHandling, decorateResult, and formatOutput. No overlap until the returns.
4. Add regression tests — ✅ 12 new tests added.

Spec compliance: The implementation matches the spec delta requirements. BigInt exponent detection uses bigint comparisons (not Math.log()), value calculation uses scaled bigint division, and values above the unit ceiling clamp to exponent 8.

Task completion: All 11 tasks in tasks.md complete.

Quality check:

• npm test: 267 tests, 0 failures
• npm run coverage: 100% statement, branch, function, and line coverage
• npm run build: succeeds
• npm run lint: passes

Note on the original issue: The issue listed 10^24 - 1 and 1024^8 - 1 as boundary bugs. Investigation showed these are actually correct float64 behavior — 10^24 - 1 is 999.999... ZB, which rounds to 1000 ZB = 1 YB at any round ≥ 0, and the fractional difference is below float64 epsilon. The genuinely fixable bug was the precision loss at 2^53, which this PR resolves. The spec and tests were updated to use values clearly below the boundary (10^24 - 10^21, 1024^8 - 1024^7) to test boundary detection without the float64 rounding ambiguity.