HF-307: warn once when a typed key enters its notice window (5/8)

[marcin-kordas-hoc]

Consumes the license key's notice field: a VALID typed key whose usage_until lies within notice days of the current UTC instant prints a single console warning naming the expiry date (with a (UTC) marker). Stacks on #1731; rebased onto its current head on 19.08 (the base moved during PR3/PR4's review passes, which had left this PR conflicting).

Why now

Per Kuba's D5-A (ClickUp, 12.08): hard blocking at/after expiry stays in 3.5.0 and the full rev 5 §4.1 window model is a follow-up — but trials made the notice warning concrete for this release: a trial is technically just a key with grace=0 and notice>0 whose warnings must surface in the console (packages meeting 12.08), and the trial mechanism lands in August.

What changed

• licenseResolution.ts: expiryWithinNoticeWindow() — usage-axis only (rev 5: notice/grace have no effect on the release_until axis), window ends exactly where the soft-stop phase would begin, blind to graceDays by design.
• licenseKeyValidator.ts: notifyLicenseKeyNotice() with per-key warn-once accounting (_noticedKeys keyed by the raw key string) — deliberately not the process-lifetime boolean the state messages use: two engines built with two different keys each get their own warning.
• Blocking behaviour at/after expiry is byte-identical to before; the key's silent flags suppress the warning; CHANGELOG entry included.

Verification

Paired tests: hyperformula-tests@spike/hf307-notice-window (authored RED-first, 8 assertions: inside/outside window, release_until never warns, expired still hard-blocks, silent suppresses, per-key warn-once across two engines). Full license suite 212/212 under Jest (12 suites, unit/license + unit/helpers/licenseKeyValidator), re-measured after the 19.08 rebase onto the current #1731 (e9863f27) — the earlier 165/165 predated PR3's and PR4's review fixes, tsc --noEmit clean, eslint --quiet clean on changed files.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches license validation and console messaging on every engine build, but changes are additive warnings with explicit silencing for transient configs and no change to expiry blocking or entitlements.

Overview
Adds a one-time console warning for valid typed license keys whose usage_until expiry falls inside the key’s configured notice window. The message names the last covered day (“valid until … (UTC)”), respects the key’s silent flags, and never runs for release_until keys or after hard expiry—blocking at/after expiry is unchanged.

licenseResolution introduces expiryWithinNoticeWindow() (usage axis only, window ends at the usage deadline, ignores grace) and only applies noticeDays for rev-5 license shapes. resolveLicense accepts notifyConsole so transient config resolution can skip console output.

licenseKeyValidator adds notifyLicenseKeyNotice() with per-key warn-once tracking (checksum-based identity), separate from the existing once-per-page invalid/missing/expired messages.

Config / mergeConfig pass notifyLicenseMessages into resolution; rebuildWithConfig silences notices for the serialization-only config built from the outgoing key while the caller may be replacing it.

^{Reviewed by Cursor Bugbot for commit db92bcd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[qunabu]

Task linked: HF-307 Implement feature packages and add-ons in HF

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	hyperformula-docs	db92bcd	Commit Preview URL Branch Preview URL	Aug 26 2026, 03:39 AM

[github-actions]

Performance comparison of head (db92bcd) vs base (cd79b06)

                                     testName |    base |   head | change
-------------------------------------------------------------------------
                                      Sheet A |   495.5 | 496.87 | +0.28%
                                      Sheet B |  162.91 | 164.61 | +1.04%
                                      Sheet T |  144.44 | 144.88 | +0.30%
                                Column ranges |  526.85 | 525.57 | -0.24%
                                Sorted lookup | 15010.7 |  14891 | -0.80%
Sheet A:  change value, add/remove row/column |   18.02 |  17.07 | -5.27%
 Sheet B: change value, add/remove row/column |  148.54 | 150.26 | +1.16%
                   Column ranges - add column |  163.96 |  161.4 | -1.56%
                Column ranges - without batch |  508.77 | 494.92 | -2.72%
                        Column ranges - batch |   126.9 | 126.63 | -0.21%

[marcin-kordas-hoc]

Paired tests PR: handsontable/hyperformula-tests#37 — merge it BEFORE this one (fetch-tests pairs by branch name).

[Tobiadefami]

Reviewed at aa835bf together with the paired tests at c832fff7. I checked the notice-window boundaries, usage/release axes, silence and warn-once behavior, config rebuild path, current automated findings, and later stacked branches. The 12 focused license suites pass (215 tests), and the current engine checks are green. I found one material boundary issue: the notice period opens one day late, as noted inline.

[Tobiadefami]

Using usageAxisDeadline to derive the start shifts the window one day late. For usage_until: 2027-08-12 and notice: 60, 60 days before the governing date is 2027-06-13T00:00:00Z, but this computes June 14; I reproduced zero warnings at the former instant. The same off-by-one means a 45-day trial with notice: 45 misses its intended first warning day. It would help to subtract noticeDays from terms.expiryTimestamp while keeping usageAxisDeadline as the exclusive end, and add an exact-boundary regression.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (hf-307-entitlement-gating-pr4@cd79b06). Learn more about missing BASE report.

Additional details and impacted files

@@                       Coverage Diff                        @@
##             hf-307-entitlement-gating-pr4    #1736   +/-   ##
================================================================
  Coverage                                 ?   97.38%           
================================================================
  Files                                    ?      204           
  Lines                                    ?    16236           
  Branches                                 ?     3493           
================================================================
  Hits                                     ?    15812           
  Misses                                   ?      424           
  Partials                                 ?        0           

Files with missing lines	Coverage Δ
src/Config.ts	94.69% <100.00%> (ø)
src/HyperFormula.ts	99.76% <100.00%> (ø)
src/helpers/licenseKeyValidator.ts	95.74% <100.00%> (ø)
src/license/licenseResolution.ts	97.43% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.