mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-02 13:22:11 +03:00
f44ec7e1f2
T-30 — ADRs:
- 6 ADRs: SQLite, Fallback Strategy, OAuth, JS+JSDoc, Single-Tenant, Translator Registry
T-33 — JSDoc Coverage:
- Full JSDoc on all new modules (100% exported functions documented)
T-35 — Accessibility:
- a11yAudit.js: lightweight WCAG AA checker (aria-label, dialog role, alt text, labels)
T-38 — Password Reset CLI:
- bin/reset-password.mjs: interactive CLI tool for admin password reset
T-39 — Playwright Specs:
- tests/e2e/responsiveSpecs.mjs: viewports (375/768/1280), 4 pages, test matrix
T-42 — Eval Framework:
- evalRunner.js: 4 strategies (exact, contains, regex, custom) + golden set (10 cases)
T-43 — Compliance:
- audit_log table, noLog opt-out per API key, LOG_RETENTION_DAYS cleanup
TASKS.md: 46/46 Concluído ✅
Tests: 144/144 pass (119 existing + 25 new)
44 lines
1.4 KiB
Markdown
44 lines
1.4 KiB
Markdown
# ADR-004: JavaScript + JSDoc over TypeScript
|
|
|
|
**Date:** 2025-10-01
|
|
**Status:** Accepted
|
|
**Deciders:** @diegosouzapw
|
|
|
|
## Context
|
|
|
|
The project needs type safety and developer experience improvements. Options:
|
|
|
|
1. **Full TypeScript migration** — `.ts` files, `tsconfig.json`, build step
|
|
2. **JavaScript + JSDoc + @ts-check** — type checking without compilation
|
|
3. **No type checking** — status quo
|
|
|
|
## Decision
|
|
|
|
Adopt **JavaScript with JSDoc annotations and `@ts-check`** instead of migrating to TypeScript.
|
|
|
|
- Add `// @ts-check` to critical module files
|
|
- Use JSDoc `@param`, `@returns`, `@typedef` for type documentation
|
|
- TypeScript compiler used only for checking (via IDE), not for building
|
|
- Zod schemas for runtime validation at API boundaries
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- No build step — `node src/proxy.js` runs directly
|
|
- Faster development iteration (no compile wait)
|
|
- Gradual adoption — files can be annotated one at a time
|
|
- IDE still provides autocomplete and type errors via JSDoc
|
|
- Lower barrier for contributors
|
|
|
|
### Negative
|
|
|
|
- JSDoc type syntax is more verbose than TypeScript
|
|
- Some advanced TypeScript features (generics, conditional types) are harder in JSDoc
|
|
- No `.d.ts` generation for consumers
|
|
|
|
### Neutral
|
|
|
|
- Existing Zod schemas provide runtime validation regardless of type system choice
|
|
- `@ts-check` can be added to any file without affecting others
|