feat(js): m01 util and m02 model with tests, fixtures, purity audit

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

js/solutions/model.js

@@ -0,0 +1,51 @@
+// m02 model: the data the whole game is built from. Plain objects, never mutated.
+
+/** @typedef {{x: number, y: number}} Point */
+/** @typedef {'Up'|'Down'|'Left'|'Right'} Direction */
+/** @typedef {'Playing'|'Paused'|'GameOver'|'Won'} Status */
+/** @typedef {{width: number, height: number, snake: Point[], dir: Direction, nextDir: Direction,
+ *   apple: Point|null, seed: number, score: number, status: Status, frame: number}} GameState */
+
+/** A grid cell. */
+export const point = (x, y) => ({ x, y })
+
+/** Structural equality: same x and same y. */
+export const pointEquals = (a, b) => a.x === b.x && a.y === b.y
+
+const deltas = {
+  Up: point(0, -1),
+  Down: point(0, 1),
+  Left: point(-1, 0),
+  Right: point(1, 0),
+}
+
+/** The unit step for a direction (y grows downward). */
+export const delta = (dir) => deltas[dir]
+
+const opposites = { Up: 'Down', Down: 'Up', Left: 'Right', Right: 'Left' }
+
+/** The direction pointing the other way. */
+export const opposite = (dir) => opposites[dir]
+
+/** Everything that can happen to the game, as data. `Turn` is a function because it carries a direction. */
+export const Action = {
+  Tick: { tag: 'Tick' },
+  Turn: (dir) => ({ tag: 'Turn', dir }),
+  TogglePause: { tag: 'TogglePause' },
+  Restart: { tag: 'Restart' },
+  Frame: { tag: 'Frame' },
+}
+
+/** A fresh 20x20 game: 3-segment snake heading Right, no apple yet. */
+export const initialState = (seed) => ({
+  width: 20,
+  height: 20,
+  snake: [point(10, 10), point(9, 10), point(8, 10)],
+  dir: 'Right',
+  nextDir: 'Right',
+  apple: null,
+  seed,
+  score: 0,
+  status: 'Playing',
+  frame: 0,
+})

js/solutions/todo.js

@@ -0,0 +1,4 @@
+// Placeholder body for unimplemented stubs: replace each `todo('mNN')` call with real code.
+export const todo = (module) => {
+  throw new Error(`TODO: implement in ${module}`)
+}

js/solutions/util.js

@@ -0,0 +1,29 @@
+// m01 util: small helpers used by every later module.
+
+/** `range(n)` is `[0, 1, ..., n-1]`; `range(0)` is `[]`. */
+export const range = (n) => Array.from({ length: n }, (_, i) => i)
+
+/** `xs` without its last element; an empty list stays empty. Never mutates `xs`. */
+export const dropLast = (xs) => xs.slice(0, -1)
+
+/** True if some element `x` of `xs` satisfies `eq(x, p)`. `eq` lets callers compare structurally (e.g. `pointEquals`). */
+export const contains = (xs, p, eq) => xs.some((x) => eq(x, p))
+
+/** `pipe(x, f, g)` is `g(f(x))`: thread a value through functions left to right. */
+export const pipe = (x, ...fns) => fns.reduce((acc, f) => f(acc), x)
+
+/** `compose(f, g)(x)` is `f(g(x))`: functions applied right to left. */
+export const compose = (...fns) => (x) => fns.reduceRight((acc, f) => f(acc), x)
+
+/**
+ * Freeze `obj` and everything reachable from it, then return it.
+ * Freezing is the one deliberate "mutation" here: it makes later accidental mutation throw.
+ */
+export const deepFreeze = (obj) => {
+  Object.freeze(obj)
+  // Freezing before recursing means cyclic structures stop at the already-frozen node.
+  Object.values(obj).forEach((v) => {
+    if (v !== null && typeof v === 'object' && !Object.isFrozen(v)) deepFreeze(v)
+  })
+  return obj
+}