Skip to content

0003-config-as-javascript.md

Latest commit

 

History

History
38 lines (26 loc) · 1.6 KB

0003-config-as-javascript.md

File metadata and controls

38 lines (26 loc) · 1.6 KB
Raw

ADR-0003 — The exam config is JavaScript, not JSON

Date: 2026-07-28 · Status: Accepted · Decided by: KalevIT

Context

ADR-0001 established one config file per exam. The obvious format was JSON.

Wiring the pages exposed a conflict with an existing product requirement: the simulator must run from disk or a USB stick with no server. Reading JSON in the browser requires fetch(), and browsers block fetch() on file:// origins. A JSON config would have broken offline use the moment the pages read the configuration — the exact scenario the project is built around.

Options

  1. Keep JSON, serve over HTTP. Requires a local web server. Breaks the USB promise.
  2. Keep JSON, add a build step generating a JS wrapper. Two files to keep in sync, and a build step in a project whose selling point is having none.
  3. Make the config a .js file assigning a global, loaded by a script tag.

Decision

Option 3. config/exam.js declares EXAM_CONFIG and exports it for Node when module exists. One file, no build step, no fetch(), readable by the browser and the CI validator alike.

Consequences

  • The offline-from-USB guarantee survives the config-driven refactor.
  • Data files follow the same pattern, for the same reason.

How this was found

Not by review. The first core.js was written against global.EXAM_CONFIG and threw on load, because a top-level const in a classic script creates a global lexical binding and not a property of globalThis. Simulating the browser load order surfaced both that bug and the fetch() constraint before either reached a commit.