chore(CI): JSDoc for headers modification date

[RobinTail]

Summary by CodeRabbit

• Chores
  • Improved internal header generation tooling with enhanced date tracking.
  • Optimized CI/CD workflow for more efficient execution.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7acf3a7e-0623-4911-9e70-8047baa11522

📥 Commits

Reviewing files that changed from the base of the PR and between 6bc852e and 02de4db.

📒 Files selected for processing (3)

• .github/workflows/headers.yml
• express-zod-api/src/well-known-headers.ts
• tools/headers.ts

💤 Files with no reviewable changes (1)

• .github/workflows/headers.yml

---

📝 Walkthrough

Walkthrough

The PR replaces git log timestamp-based freshness checks in the header generation tool with self-documenting @since ISO date markers embedded in the generated module itself, allowing the CI workflow to use shallow git checkout.

Changes

Header Generation Self-Timing via @since Marker

Layer / File(s)	Summary
Generation Tool - Early Exit with @since Parsing tools/headers.ts	Import readFile; add early-exit logic that reads existing generated file, parses @since ISO date via regex, and exits when stored date ≥ fetched IANA Last-Modified date; remove execSync mtime calculation; update generated TypeScript source to include JSDoc @since annotation populated from Last-Modified.
Generated Module Annotation express-zod-api/src/well-known-headers.ts	JSDoc @since annotation inserted above getWellKnownHeaders export.
Workflow Checkout Optimization .github/workflows/headers.yml	Remove with.fetch-depth: 0 from actions/checkout step since generation tool no longer requires full git history.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• RobinTail/express-zod-api#3014: Both PRs modify the header-generation pipeline in tools/headers.ts and the generated express-zod-api/src/well-known-headers.ts—the prior PR switched generation to TypeScript with Prettier formatting; this PR adds self-documenting @since markers and timestamp-free freshness checks.
• RobinTail/express-zod-api#3351: Both PRs modify the well-known-headers generation and export shape—ref(mem,perf): Turning well-known headers into a Set #3351 replaced the array export with a cached getWellKnownHeaders Set; this PR updates the generation tool and adds JSDoc @since to the same export.

Suggested labels

CI/CD

Poem

🐰 No more git logs, no more shallow fears,
A timestamp marker appears!
The headers know when they were born,
Fresh-checked each dawn,
Shallow checkouts now bring good cheer! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: replacing git log-based mtime logic with a JSDoc @since annotation for tracking header modification dates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch better-mod-headers-date

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pullfrog]

No new issues found.

TL;DR — Replaces the git log-based mtime dedup in the headers-update tooling with a self-describing @since JSDoc tag inside the generated file, and drops the fetch-depth: 0 checkout that was only needed for the old approach.

Key changes

• Embed @since tag in generated headers file — tools/headers.ts now reads the previous IANA Last-Modified value out of well-known-headers.ts instead of shelling out to git log.
• Seed the tag in the generated file — well-known-headers.ts gains /** @since 2026-03-06T22:01:19.000Z */ so the first post-merge run is bootstrapped and does not silently regenerate.
• Drop fetch-depth: 0 from the workflow — .github/workflows/headers.yml no longer needs full git history now that the tool does not call git log.

_{Summary ｜ 3 files ｜ 1 commit ｜ base: master ← better-mod-headers-date}

Self-describing dedup via @since

Before: tools/headers.ts ran git log -1 --pretty="format:%ci" <dest> to get the last commit date of the generated file, then skipped regeneration if IANA's Last-Modified was older.
After: the tool parses @since out of the generated file with /@since\s+(\S+)/, compares the stored Date against IANA's Last-Modified, and exits early when since >= state.

The new comparison is actually tighter than the old one: it compares IANA's Last-Modified against the previously-stored IANA Last-Modified, instead of against an unrelated git commit timestamp. Round-tripping through state.toISOString() is lossless for HTTP-date second precision, so the equality boundary is correct. Failure modes (no @since match, unparseable date, non-ENOENT read errors) all fall through to regeneration, which is the safe default.

tools/headers.ts · express-zod-api/src/well-known-headers.ts · .github/workflows/headers.yml

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[coveralls-official]

coverage: 100.0%. remained the same — better-mod-headers-date into master