feat(models): auto-generate JSDoc annotations

[hanna-skryl]

Closes #827

This PR introduces a TypeScript transformer that automatically generates JSDoc annotations for type definitions within the models package. The transformer ensures that all Zod-based schemas are documented with reference links, providing easy navigation to Markdown documentation.

Demo

[github-actions]

Code PushUp

🤨 Code PushUp report has both improvements and regressions – compared target commit 69a382c with source commit 6c7ed9f.

🕵️ See full comparison in Code PushUp portal 🔍

🏷️ Categories

🏷️ Category	⭐ Previous score	⭐ Current score	🔄 Score change
Performance	🟡 52	🟡 52
Updates	🟡 77	🟡 77
Code coverage	🟢 91	🟢 91
Documentation	🔴 23	🔴 23
Security	🟡 79	🟡 79	–
Accessibility	🟢 92	🟢 92	–
Best Practices	🟢 100	🟢 100	–
SEO	🟡 61	🟡 61	–
Bug prevention	🟢 100	🟢 100	–
Code style	🟢 100	🟢 100	–

👍 2 groups improved, 👎 2 groups regressed, 👍 2 audits improved, 👎 8 audits regressed, 10 audits changed without impacting score

🗃️ Groups

🔌 Plugin	🗃️ Group	⭐ Previous score	⭐ Current score	🔄 Score change
Lighthouse	Performance	🟡 52	🟡 52
JS Packages	NPM outdated dependencies	🟡 77	🟡 77
Code coverage	Code coverage metrics	🟢 91	🟢 91
JSDoc coverage	Documentation coverage	🔴 23	🔴 23

14 other groups are unchanged.

🛡️ Audits

🔌 Plugin	🛡️ Audit	📏 Previous value	📏 Current value	🔄 Value change
Lighthouse	Speed Index	🟨 5.1 s	🟨 5.7 s
Lighthouse	Largest Contentful Paint	🟨 3.7 s	🟨 3.5 s
Lighthouse	First Contentful Paint	🟨 2.7 s	🟨 2.8 s
Lighthouse	Total Blocking Time	🟥 3,740 ms	🟥 4,840 ms
Lighthouse	Time to Interactive	🟥 14.1 s	🟥 14.8 s
JS Packages	Outdated NPM dev dependencies.	🟨 47 outdated package versions (25 major, 14 minor, 8 patch)	🟨 47 outdated package versions (25 major, 14 minor, 8 patch)
Code coverage	Line coverage	🟩 90.1 %	🟨 89.8 %
Code coverage	Branch coverage	🟨 86 %	🟨 85.9 %
JSDoc coverage	Functions coverage	🟥 437 undocumented functions	🟥 439 undocumented functions
JSDoc coverage	Variables coverage	🟥 197 undocumented variables	🟥 200 undocumented variables
Lighthouse	Avoids enormous network payloads	🟩 Total size was 1,808 KiB	🟩 Total size was 1,812 KiB
Lighthouse	Minimizes main-thread work	🟥 13.0 s	🟥 15.7 s
Lighthouse	Max Potential First Input Delay	🟥 2,660 ms	🟥 1,820 ms
Lighthouse	Metrics	🟩 100%	🟩 100%
Lighthouse	JavaScript execution time	🟥 7.1 s	🟥 7.6 s
Lighthouse	Uses efficient cache policy on static assets	🟨 27 resources found	🟨 27 resources found
Lighthouse	Initial server response time was short	🟩 Root document took 340 ms	🟩 Root document took 450 ms
Lighthouse	Server Backend Latencies	🟩 110 ms	🟩 170 ms
Lighthouse	Network Round Trip Times	🟩 20 ms	🟩 50 ms
Lighthouse	Eliminate render-blocking resources	🟥 Potential savings of 900 ms	🟥 Potential savings of 870 ms

576 other audits are unchanged.

[vmasek]

Really nice! I just found out few days ago about transformers in TS and how powerful they are and this is really amazing DX & UX improvement

[matejchalk]

Amazing 😍 Good to learn about transformers 😁 Very elegant solution 💯