@playcraft/cli 0.0.55 → 0.0.56

package/project-template/skills/_shared/scripts/validate-level-sketch.mjs

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+/**
+ * Validate docs/level-sketch.json — solvability + puzzle identity + difficulty profiles.
+ * Pure JS — no TS runtime dependency.
+ *
+ * Env: LEVEL_DIFFICULTY_PROFILE=ring1_min|standard|hard
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+
+export const DIFFICULTY_PROFILES = {
+  ring1_min: {
+    boardRow: 8,
+    boardCol: 8,
+    minPaths: 6,
+    minSegments: 12,
+    minDependencyDepth: 2,
+    maxOpeningRemovable: 2,
+    maxTrayPeak: 5,
+  },
+  standard: {
+    boardRow: 8,
+    boardCol: 8,
+    minPaths: 9,
+    minSegments: 18,
+    minDependencyDepth: 3,
+    maxOpeningRemovable: 3,
+    maxTrayPeak: 6,
+  },
+  hard: {
+    boardRow: 8,
+    boardCol: 8,
+    minPaths: 12,
+    minSegments: 24,
+    minDependencyDepth: 4,
+    maxOpeningRemovable: 1,
+    maxTrayPeak: 7,
+  },
+};
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), sketch: 'docs/level-sketch.json', json: false };
+  for (const arg of argv) {
+    if (arg === '--json') opts.json = true;
+    else if (arg.startsWith('--root=')) opts.root = resolve(arg.slice('--root='.length));
+    else if (arg.startsWith('--sketch=')) opts.sketch = arg.slice('--sketch='.length);
+    else if (arg.startsWith('--profile=')) opts.profile = arg.slice('--profile='.length);
+  }
+  return opts;
+}
+
+/** @typedef {{ x: number, y: number }} GridPoint */
+/** @typedef {{ points: GridPoint[], head: GridPoint, direction: string, color: string, indices: number[], segments: number }} LevelPath */
+/** @typedef {{ index: number, rows: number, cols: number, paths: LevelPath[], levelTime: number, trayCapacity: number, matchCount: number, boardPhases: unknown[] | null }} ParsedLevel */
+
+function pathSegments(points) {
+  return points.length <= 1 ? 0 : points.length - 1;
+}
+
+/** @param {unknown} raw @returns {ParsedLevel} */
+export function parseLevelSketch(raw) {
+  let target = raw;
+  if (Array.isArray(raw)) {
+    const maybe = raw[5];
+    if (Array.isArray(maybe) && Array.isArray(maybe[0]) && maybe[0].length >= 3) {
+      target = maybe[0][2];
+    }
+  }
+  if (typeof target !== 'object' || target === null) {
+    throw new Error('Invalid level sketch: expected object');
+  }
+  const obj = /** @type {Record<string, unknown>} */ (target);
+  const rows = typeof obj.row === 'number' ? obj.row : 8;
+  const cols = typeof obj.col === 'number' ? obj.col : 8;
+  const trayCapacity = typeof obj.trayCapacity === 'number' ? obj.trayCapacity : 7;
+  const matchCount = typeof obj.matchCount === 'number' ? obj.matchCount : 3;
+  const colorList = Array.isArray(obj.colors) ? obj.colors : [];
+  const rawArrows = Array.isArray(obj.arrows) ? obj.arrows : [];
+
+  const paths = rawArrows.map((rawPath, pathIndex) => {
+    if (!Array.isArray(rawPath)) throw new Error(`paths[${pathIndex}] must be array`);
+    const points = rawPath.map((p, pi) => {
+      if (!Array.isArray(p) || p.length < 2) throw new Error(`paths[${pathIndex}][${pi}] invalid`);
+      const [x, cocosY] = /** @type {[number, number]} */ (p);
+      const colorFromPoint = typeof p[2] === 'string' ? p[2] : undefined;
+      return { x, y: rows > 0 ? rows - 1 - cocosY : cocosY, colorFromPoint };
+    });
+    if (points.length === 0) {
+      return {
+        points: [],
+        head: { x: 0, y: 0 },
+        direction: 'right',
+        color: colorList[pathIndex] ?? `color_${pathIndex % 3}`,
+        indices: [],
+        segments: 0,
+      };
+    }
+    const head = points[points.length - 1];
+    const before = points[Math.max(0, points.length - 2)];
+    const dx = head.x - before.x;
+    const dy = head.y - before.y;
+    let direction = 'right';
+    if (Math.abs(dx) >= Math.abs(dy)) direction = dx < 0 ? 'left' : 'right';
+    else direction = dy < 0 ? 'up' : 'down';
+    const indices = points.map((pt) => pt.y * cols + pt.x);
+    const color =
+      colorList[pathIndex] ??
+      points.find((p) => p.colorFromPoint)?.colorFromPoint ??
+      `color_${pathIndex % 3}`;
+
+    return {
+      points: points.map((p) => ({ x: p.x, y: p.y })),
+      head,
+      direction,
+      color,
+      indices,
+      segments: pathSegments(points.map((p) => [p.x, p.y])),
+    };
+  });
+
+  return {
+    index: typeof obj.name === 'number' ? obj.name : 0,
+    rows,
+    cols,
+    paths,
+    levelTime: typeof obj.levelTime === 'number' ? obj.levelTime : 0,
+    trayCapacity,
+    matchCount,
+    boardPhases: Array.isArray(obj.boardPhases) ? obj.boardPhases : null,
+  };
+}
+
+/** @param {ParsedLevel} level @param {number} pathIndex @param {Set<number>} removed */
+export function canPathExitBoard(level, pathIndex, removed) {
+  const path = level.paths[pathIndex];
+  if (!path) return { canExit: false };
+  const delta =
+    path.direction === 'left'
+      ? { dx: -1, dy: 0 }
+      : path.direction === 'right'
+        ? { dx: 1, dy: 0 }
+        : path.direction === 'up'
+          ? { dx: 0, dy: -1 }
+          : { dx: 0, dy: 1 };
+  const occupied = new Set();
+  for (let i = 0; i < level.paths.length; i++) {
+    if (i === pathIndex || removed.has(i)) continue;
+    for (const idx of level.paths[i].indices) occupied.add(idx);
+  }
+  let x = path.head.x;
+  let y = path.head.y;
+  for (let step = 0; step < Math.max(level.rows, level.cols) + 2; step += 1) {
+    x += delta.dx;
+    y += delta.dy;
+    if (x < 0 || x >= level.cols || y < 0 || y >= level.rows) return { canExit: true };
+    if (occupied.has(y * level.cols + x)) return { canExit: false };
+  }
+  return { canExit: false };
+}
+
+/** @param {ParsedLevel} level */
+export function countOpeningRemovable(level) {
+  const removed = new Set();
+  let count = 0;
+  for (let i = 0; i < level.paths.length; i += 1) {
+    if (canPathExitBoard(level, i, removed).canExit) count += 1;
+  }
+  return count;
+}
+
+/** @param {ParsedLevel} level */
+export function computeDependencyDepth(level) {
+  const removed = new Set();
+  let depth = 0;
+  let remaining = level.paths.length;
+
+  while (remaining > 0) {
+    const wave = [];
+    for (let i = 0; i < level.paths.length; i += 1) {
+      if (removed.has(i)) continue;
+      if (canPathExitBoard(level, i, removed).canExit) wave.push(i);
+    }
+    if (wave.length === 0) return -1;
+    depth += 1;
+    for (const i of wave) removed.add(i);
+    remaining -= wave.length;
+  }
+  return depth;
+}
+
+/** @param {ParsedLevel} level */
+export function totalSegments(level) {
+  return level.paths.reduce((sum, p) => sum + p.segments, 0);
+}
+
+/** @param {ParsedLevel} level */
+export function occupationRatio(level) {
+  const cells = new Set();
+  for (const path of level.paths) {
+    for (const idx of path.indices) cells.add(idx);
+  }
+  const area = level.rows * level.cols;
+  return area > 0 ? cells.size / area : 0;
+}
+
+/** @param {ParsedLevel} level */
+export function simulateTrayPeak(level) {
+  const colorGroups = new Map();
+  for (const path of level.paths) {
+    const list = colorGroups.get(path.color) || [];
+    list.push(path.pathIndex);
+    colorGroups.set(path.color, list);
+  }
+
+  let traySize = 0;
+  let peak = 0;
+  for (const [, pathIndices] of colorGroups) {
+    traySize += pathIndices.length;
+    peak = Math.max(peak, traySize);
+    const matches = Math.floor(pathIndices.length / level.matchCount);
+    traySize -= matches * level.matchCount;
+  }
+  return peak;
+}
+
+/** @param {ParsedLevel} level */
+export function checkOverlap(level) {
+  const errors = [];
+  const seen = new Map();
+  for (const path of level.paths) {
+    for (const idx of path.indices) {
+      if (seen.has(idx)) {
+        errors.push(`Paths ${seen.get(idx)} and ${path.pathIndex} overlap at cell ${idx}`);
+      } else {
+        seen.set(idx, path.pathIndex);
+      }
+    }
+  }
+  return errors;
+}
+
+/** @param {ParsedLevel} level */
+export function validateLevelSolvable(level) {
+  const removed = new Set();
+  while (removed.size < level.paths.length) {
+    let found = null;
+    for (let i = 0; i < level.paths.length; i++) {
+      if (removed.has(i)) continue;
+      if (canPathExitBoard(level, i, removed).canExit) {
+        found = i;
+        break;
+      }
+    }
+    if (found === null) {
+      return {
+        solvable: false,
+        reason: `greedy stuck after removing ${removed.size}/${level.paths.length} paths`,
+      };
+    }
+    removed.add(found);
+  }
+  return { solvable: true };
+}
+
+/**
+ * @param {ParsedLevel} level
+ * @param {keyof typeof DIFFICULTY_PROFILES} profileName
+ */
+export function validateDifficulty(level, profileName = 'ring1_min') {
+  const profile = DIFFICULTY_PROFILES[profileName];
+  if (!profile) {
+    return { errors: [`Unknown difficulty profile: ${profileName}`], warnings: [], metrics: {} };
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  if (level.rows !== profile.boardRow || level.cols !== profile.boardCol) {
+    errors.push(
+      `Board must be ${profile.boardRow}×${profile.boardCol} for profile ${profileName}, got ${level.rows}×${level.cols}`,
+    );
+  }
+
+  if (level.paths.length < profile.minPaths) {
+    errors.push(`Too few paths: ${level.paths.length} < ${profile.minPaths} (${profileName})`);
+  }
+
+  const segments = totalSegments(level);
+  if (segments < profile.minSegments) {
+    errors.push(`Too few segments: ${segments} < ${profile.minSegments} (${profileName})`);
+  }
+
+  const opening = countOpeningRemovable(level);
+  if (opening >= level.paths.length && level.paths.length > 1) {
+    errors.push('All paths are FREE at opening — zero decision puzzle (anti-pattern)');
+  } else if (opening > profile.maxOpeningRemovable) {
+    warnings.push(
+      `Opening removable ${opening} > max ${profile.maxOpeningRemovable} for ${profileName}`,
+    );
+  }
+
+  const depDepth = computeDependencyDepth(level);
+  if (depDepth < 0) {
+    errors.push('Dependency graph is not solvable (deadlock in greedy waves)');
+  } else if (depDepth < profile.minDependencyDepth) {
+    errors.push(`Dependency depth ${depDepth} < ${profile.minDependencyDepth} (${profileName})`);
+  }
+
+  const trayPeak = simulateTrayPeak(level);
+  if (trayPeak > profile.maxTrayPeak) {
+    errors.push(`Tray peak ${trayPeak} > ${profile.maxTrayPeak} (${profileName})`);
+  }
+
+  const occupancy = occupationRatio(level);
+  if (occupancy < 0.4) {
+    warnings.push(`Occupancy ${(occupancy * 100).toFixed(0)}% < 40% — board may feel sparse`);
+  }
+
+  return {
+    errors,
+    warnings,
+    metrics: { segmentCount: segments, segments, opening, dependencyDepth: depDepth, depDepth, trayPeakSimulated: trayPeak, trayPeak, occupancy },
+  };
+}
+
+/** @param {ParsedLevel} level */
+export function validateBoardPhases(level) {
+  if (!level.boardPhases || level.boardPhases.length === 0) return [];
+  const errors = [];
+  for (const [i, phase] of level.boardPhases.entries()) {
+    if (!phase || typeof phase !== 'object') {
+      errors.push(`boardPhases[${i}] must be an object`);
+      continue;
+    }
+    const p = /** @type {Record<string, unknown>} */ (phase);
+    if (!p.phaseId) errors.push(`boardPhases[${i}] missing phaseId`);
+    if (!p.activeMask && !p.mask) {
+      errors.push(`boardPhases[${i}] missing activeMask or mask`);
+    }
+    if (!p.unlockAfter) {
+      errors.push(`boardPhases[${i}] missing unlockAfter (e.g. matchClears or pathsRemoved)`);
+    }
+  }
+  return errors;
+}
+
+/** @param {string} root @param {string} sketchRel @param {{ profile?: string }} [options] */
+export function validateLevelSketch(root, sketchRel = 'docs/level-sketch.json', options = {}) {
+  const sketchPath = join(root, sketchRel);
+  const profileName =
+    options.profile ??
+    process.env.LEVEL_DIFFICULTY_PROFILE ??
+    'ring1_min';
+
+  if (!existsSync(sketchPath)) {
+    return {
+      ok: false,
+      problems: [`level sketch not found: ${sketchRel}`],
+      metrics: {
+        pathCount: 0,
+        openingRemovableCount: 0,
+        hasBlockedPaths: false,
+        solvable: false,
+        segmentCount: 0,
+        dependencyDepth: 0,
+        trayPeakSimulated: 0,
+      },
+      profile: profileName,
+    };
+  }
+
+  const problems = [];
+  const warnings = [];
+  let level;
+  try {
+    level = parseLevelSketch(JSON.parse(readFileSync(sketchPath, 'utf8')));
+  } catch (err) {
+    return {
+      ok: false,
+      problems: [`parse error: ${err instanceof Error ? err.message : String(err)}`],
+      metrics: {
+        pathCount: 0,
+        openingRemovableCount: 0,
+        hasBlockedPaths: false,
+        solvable: false,
+        segmentCount: 0,
+        dependencyDepth: 0,
+        trayPeakSimulated: 0,
+      },
+      profile: profileName,
+    };
+  }
+
+  problems.push(...checkOverlap(level));
+  problems.push(...validateBoardPhases(level));
+
+  const openingRemovableCount = countOpeningRemovable(level);
+  const solvability = validateLevelSolvable(level);
+  const diff = validateDifficulty(level, profileName);
+  warnings.push(...(diff.warnings ?? []));
+  problems.push(...diff.errors);
+
+  if (level.paths.length < 3) {
+    problems.push('level sketch should include at least 3 paths for Ring 1 gameplay identity');
+  }
+  if (!solvability.solvable) {
+    problems.push(solvability.reason ?? 'level is not solvable');
+  }
+
+  const metrics = {
+    pathCount: level.paths.length,
+    openingRemovableCount,
+    hasBlockedPaths: level.paths.length > openingRemovableCount,
+    solvable: solvability.solvable,
+    solvabilityReason: solvability.reason,
+    segmentCount: diff.metrics?.segmentCount ?? totalSegments(level),
+    dependencyDepth: diff.metrics?.dependencyDepth ?? computeDependencyDepth(level),
+    trayPeakSimulated: diff.metrics?.trayPeakSimulated ?? simulateTrayPeak(level),
+    occupancy: diff.metrics?.occupancy ?? occupationRatio(level),
+    boardSize: `${level.rows}x${level.cols}`,
+  };
+
+  return { ok: problems.length === 0, problems, warnings, metrics, profile: profileName };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = validateLevelSketch(opts.root, opts.sketch, { profile: opts.profile });
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else if (result.ok) {
+    process.stdout.write(
+      `[levels validate] OK (${result.profile}) — paths=${result.metrics.pathCount} openingRemovable=${result.metrics.openingRemovableCount} segments=${result.metrics.segmentCount}\n`,
+    );
+    for (const w of result.warnings ?? []) process.stderr.write(`  WARN: ${w}\n`);
+  } else {
+    process.stderr.write(`[levels validate] FAIL\n  - ${result.problems.join('\n  - ')}\n`);
+  }
+  process.exit(result.ok ? 0 : 2);
+}
+
+if (process.argv[1] && basename(process.argv[1]) === 'validate-level-sketch.mjs') {
+  main();
+}