scaffold-exercises

Scaffold exercises

Contract

Inputs

Must be supplied:

• section — the section number as a non-negative integer (e.g. 1, 2, 3)
• exercise — the exercise number as a positive integer
• type — one of: problem, solution, explainer
• base_path — the directory under which sections and exercises live (must be a tracked VCS path)

Procedure

1. Validate inputs and base_path. Confirm section is a non-negative integer, exercise is a positive integer, type is one of the three allowed values, and base_path is a non-empty string pointing to a directory that exists and is tracked by the local VCS. Stop on any validation failure without writing. Done when: all inputs pass validation.

2. Compute the section subdirectory and a type-specific exercise filename. The section subdirectory is base_path/section-N where N is the section number left-padded to two digits. The exercise filename is exercise-M-<type>.md where M is the exercise number left-padded to two digits and <type> is the supplied type value. The three types produce distinct filenames (exercise-M-problem.md, exercise-M-solution.md, exercise-M-explainer.md) so they do not collide or overwrite each other. Done when: the subdirectory and filename are computed.

3. Create the directory chain and file. Create the section subdirectory if it does not exist. Create the exercise file at the computed path. Done when: the directory chain and file exist.

4. Populate the scaffold with the type-specific heading. For problem: emit ## Exercise N.N where N.N is section.exercise, then a blank line, then a fenced code block with the language unspecified. For solution: emit ## Exercise N.N Solution, then a blank line. For explainer: emit ## Exercise N.N Explained, then a blank line. Write the populated content to the file. If the write fails, stop and report the failure. Done when: the file contains the type-specific heading and scaffold.