JSON Settings Checker

Project roadmap

1. 01

   Define the settings and output

   ~1h

   Write README.md with an example settings file (for example server with host and port, database with url and pool size, and a list of feature flags) and the exact rules for each field. Show the expected output for a valid file and for a file with several mistakes. Create an sbt project with circe-parser, cats-core, cats-effect and munit. Done when: README.md shows the rules and example output.

2. 02

   Model the settings

   ~1.5h

   Define case classes for the settings (Settings, Server, Database). Write a function that reads a field at a path from a Circe Json value and reports errors with the full path (such as database.poolSize), for missing fields and wrong types (a text where a number is expected). Done when: reading a correct file produces a Settings value, and unit tests show clear errors for missing fields and wrong types.

3. 03

   Validate and collect all errors

   ~2h

   Use ValidatedNel[String, A] for each field's checks (port range, a URL starting with postgres://, pool size between 1 and 100, feature names from a known list) and combine them with mapN, so all errors are collected instead of stopping at the first. Also warn about unknown fields, which are often typos. Done when: a file with 4 mistakes reports all 4 with their paths.

4. 04

   Build the command

   ~1.5h

   Write an IOApp that reads the file path from the arguments, reads the file (reporting when it's missing or unreadable), parses the JSON (reporting the line and column of syntax errors), and validates it. Print OK or the list of errors, and return exit code 0 when valid and 1 otherwise. Done when: running the tool on valid and invalid files prints the right output and exit code.

5. 05

   Handle edge cases

   ~1h

   Handle an empty file, a file containing a JSON array or number instead of an object, null values, and very large numbers. Add a --json option that prints the errors as JSON, for use in scripts. Done when: each edge case gives a clear message instead of a crash.

6. 06

   Test it

   ~1.5h

   Write munit tests with sample files in test resources: a valid file, each rule broken on its own, several rules broken together, syntax errors, and unknown fields. Check the exact messages and paths. Done when: sbt test passes.

Resources

• DocsScala 3 book
• DocsCirce documentation
• DocsCats: Validated
• DocsCats Effect: getting started
• Docsmunit documentation