the-beacon/scripts/reckoning_chain_validator.cjs

#!/usr/bin/env node
const fs = require('node:fs');
const path = require('node:path');

function extractProjects(source) {
  const start = source.indexOf('const PDEFS = [');
  if (start === -1) return [];
  const arrayStart = source.indexOf('[', start);
  const arrayEnd = source.indexOf('];', arrayStart);
  const body = source.slice(arrayStart + 1, arrayEnd);
  const objects = [];
  let depth = 0;
  let objStart = -1;
  let inSingle = false;
  let inDouble = false;
  let escaped = false;

  for (let i = 0; i < body.length; i += 1) {
    const ch = body[i];
    if (escaped) {
      escaped = false;
      continue;
    }
    if (ch === '\\') {
      escaped = true;
      continue;
    }
    if (!inDouble && ch === "'") {
      inSingle = !inSingle;
      continue;
    }
    if (!inSingle && ch === '"') {
      inDouble = !inDouble;
      continue;
    }
    if (inSingle || inDouble) continue;

    if (ch === '{') {
      if (depth === 0) objStart = i;
      depth += 1;
    } else if (ch === '}') {
      depth -= 1;
      if (depth === 0 && objStart !== -1) {
        objects.push(body.slice(objStart, i + 1));
        objStart = -1;
      }
    }
  }

  return objects.map((obj) => {
    const id = /id:\s*'([^']+)'/.exec(obj);
    const name = /name:\s*'([^']+)'/.exec(obj);
    const trigger = new RegExp(String.raw`trigger:\s*\(\)\s*=>\s*([\s\S]*?)(?:,\s*effect:|,\s*repeatable:|,\s*milestone:|\n\s*\})`).exec(obj);
    const effect = /effect:\s*\(\)\s*=>\s*\{([\s\S]*?)\}/.exec(obj);
    return {
      id: id ? id[1] : null,
      name: name ? name[1] : '',
      trigger: trigger ? trigger[1].trim() : '',
      effect: effect ? effect[1].trim() : '',
    };
  }).filter((project) => project.id);
}

function buildDependencyGraph(projects) {
  const ids = new Set(projects.map((project) => project.id));
  const nodes = projects.map((project) => ({ id: project.id, name: project.name }));
  const edges = [];

  for (const project of projects) {
    for (const dep of ids) {
      const token = `includes('${dep}')`;
      if (project.trigger.includes(token)) {
        edges.push({ from: dep, to: project.id, reason: 'completedProjects.includes' });
      }
    }
  }

  return { nodes, edges };
}

function isTerminalProject(project) {
  return [
    'G.beaconEnding = true',
    'G.dismantleTriggered = true',
    'G.dismantleActive = true',
    'renderBeaconEnding',
    'renderDriftEnding',
  ].some((token) => project.effect.includes(token));
}

function analyzeReckoningChain(projects) {
  const graph = buildDependencyGraph(projects);
  const reckoningProjects = projects
    .filter((project) => project.id.startsWith('p_reckoning_'))
    .sort((a, b) => a.id.localeCompare(b.id));

  const deadEnds = [];
  const fixProposals = [];

  if (reckoningProjects.length === 0) {
    deadEnds.push({
      type: 'missing_root_project',
      message: 'No ReCKoning projects exist in js/data.js.',
    });
    fixProposals.push({
      type: 'create_chain',
      proposals: [
        'p_reckoning_140',
        'p_reckoning_141',
        'p_reckoning_142',
        'p_reckoning_143',
        'p_reckoning_144',
      ],
      rationale: 'Create a narrative chain with at least one terminal project so endgame guardrails have a live project path.',
    });
    return {
      totalProjects: projects.length,
      totalEdges: graph.edges.length,
      reckoningProjects: [],
      hasReckoningProjects: false,
      deadEnds,
      fixProposals,
    };
  }

  const outgoing = new Map();
  for (const project of reckoningProjects) {
    outgoing.set(project.id, graph.edges.filter((edge) => edge.from === project.id).map((edge) => edge.to));
  }

  const ids = reckoningProjects.map((project) => project.id);
  const root = 'p_reckoning_140';
  if (!ids.includes(root)) {
    deadEnds.push({
      type: 'missing_expected_root',
      message: `Expected root project ${root} is missing.`,
    });
    fixProposals.push({
      type: 'add_root',
      project: root,
      rationale: 'Root project anchors the ReCKoning chain and prevents the endgame panel from opening empty.',
    });
  }

  for (const project of reckoningProjects) {
    const next = outgoing.get(project.id) || [];
    if (next.length === 0 && !isTerminalProject(project)) {
      deadEnds.push({
        type: 'leaf_without_terminal_effect',
        project: project.id,
        message: `${project.id} unlocks nothing downstream and does not end the sequence.`,
      });
      const num = Number(project.id.split('_').pop());
      if (Number.isFinite(num)) {
        fixProposals.push({
          type: 'add_missing_link',
          after: project.id,
          project: `p_reckoning_${num + 1}`,
          rationale: 'Add the next narrative project or mark this node as a true terminal endgame effect.',
        });
      }
    }
  }

  return {
    totalProjects: projects.length,
    totalEdges: graph.edges.length,
    reckoningProjects: reckoningProjects.map((project) => ({
      id: project.id,
      name: project.name,
      outgoing: outgoing.get(project.id) || [],
      terminal: isTerminalProject(project),
    })),
    hasReckoningProjects: true,
    deadEnds,
    fixProposals,
  };
}

function loadSource(filePath) {
  return fs.readFileSync(filePath, 'utf8');
}

function generateReport(filePath) {
  const source = loadSource(filePath);
  const projects = extractProjects(source);
  return analyzeReckoningChain(projects);
}

function parseArgs(argv) {
  const args = {
    file: path.resolve(process.cwd(), 'js', 'data.js'),
    json: false,
    strict: false,
  };
  for (let i = 0; i < argv.length; i += 1) {
    const arg = argv[i];
    if (arg === '--file') {
      args.file = path.resolve(process.cwd(), argv[i + 1]);
      i += 1;
    } else if (arg === '--json') {
      args.json = true;
    } else if (arg === '--strict') {
      args.strict = true;
    }
  }
  return args;
}

function main(argv = process.argv.slice(2)) {
  const args = parseArgs(argv);
  const report = generateReport(args.file);
  if (args.json) {
    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
  } else {
    process.stdout.write(`ReCKoning projects: ${report.reckoningProjects.length}\n`);
    process.stdout.write(`Dead ends: ${report.deadEnds.length}\n`);
  }
  if (args.strict && report.deadEnds.length > 0) {
    return 1;
  }
  return 0;
}

module.exports = {
  extractProjects,
  buildDependencyGraph,
  analyzeReckoningChain,
  generateReport,
  main,
};

if (require.main === module) {
  process.exitCode = main();
}