Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

6.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  check-decision-inventory.mjs — the declared runtime decisions still say
 *        something true, and the debt between their three surfaces is counted.
 *
 * runtimeDecisions.mjs names, for each choice the engine makes on a creator's
 * behalf, whether the runtime records WHY, whether the editor shows it, and
 * whether the automation surface answers the same question. This holds those
 * claims against the tree: a probe that no longer finds its subject is a finding,
 * not documentation, and an `owed` that has quietly been paid is bookkeeping that
 * stopped being true.
 *
 * It reports rather than ratchets. The debt here is a roadmap, not a regression:
 * failing on its size would only invite entries to be deleted. What it FAILS on
 * is a lie — a citation pointing nowhere, or a surface claimed and unfindable.
 *
 *   node tools/check-decision-inventory.mjs [--list]
 */
import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { DECISIONS } from './lib/runtimeDecisions.mjs';

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const SURFACES = ['runtime', 'editor', 'agent'];

const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');

/** Every file under a directory, so a directory citation can be probed. */
function filesUnder(dir, out = []) {
  for (const entry of readdirSync(dir)) {
    const full = path.join(dir, entry);
    if (statSync(full).isDirectory()) filesUnder(full, out);
    else out.push(full);
  }
  return out;
}

/** Null when the citation still finds what it says, else why not. */
function probeHolds(cite) {
  const full = path.join(ROOT, cite.path);
  if (!existsSync(full)) return 'does not exist';
  if (cite.dir) {
    for (const f of filesUnder(full)) {
      if (cite.probe.test(readFileSync(f, 'utf8'))) return null;
    }
    return `no file under it matches ${cite.probe}`;
  }
  return cite.probe.test(read(cite.path)) ? null : `does not match ${cite.probe}`;
}

// The editor is an optional submodule; a citation into it cannot be judged
// without one. Named, never rounded down to a pass.
const HAS_EDITOR = existsSync(path.join(ROOT, 'desktop', 'src'));

const problems = [];
const skipped = [];
const owed = [];
let claimed = 0;

for (const d of DECISIONS) {
  const cites = [['owner', d.owner], ...SURFACES.map((s) => [s, d[s]?.has ? d[s].cite : null])];
  for (const [role, cite] of cites) {
    if (!cite) continue;
    if (!HAS_EDITOR && cite.path.startsWith('desktop/')) { skipped.push(`${d.id} → ${role}`); continue; }
    claimed++;
    const why = probeHolds(cite);
    if (why) problems.push(`${d.id} → ${role}: ${cite.path} ${why}`);
  }
  for (const s of SURFACES) {
    const surface = d[s];
    if (!surface) { problems.push(`${d.id} says nothing about its ${s} surface`); continue; }
    if (!surface.has && !surface.owed && !surface.unavailable) {
      problems.push(`${d.id} → ${s} is absent with no reason`);
    }
    if (surface.has && (surface.owed || surface.unavailable)) {
      problems.push(`${d.id} → ${s} both claims a surface and explains its absence`);
    }
    // `unavailable` is a claim about the CODE, and prose carries no probe — so
    // residency's premise outlived the release that removed it. This one holds
    // the OPPOSITE way round: the premise still being findable keeps it true.
    if (surface.unavailable) {
      if (!surface.while) {
        problems.push(`${d.id} → ${s} is unavailable with nothing to disprove it — add \`while\``);
      } else if (!(!HAS_EDITOR && surface.while.path.startsWith('desktop/'))) {
        claimed++;
        const gone = probeHolds(surface.while);
        if (gone) {
          problems.push(
            `${d.id} → ${s}: the premise for calling it unavailable is gone `
            + `(${surface.while.path} ${gone}) — the surface may be buildable now`);
        }
      }
    }
    // Two defects, counted apart: one is a reader nobody wrote, the other is a
    // fact this realm never produces. Only the first is a panel.
    if (!surface.has) {
      owed.push({
        id: d.id, surface: s, why: surface.owed ?? surface.unavailable,
        kind: surface.unavailable ? 'unavailable' : 'owed',
      });
    }
  }
}

/**
 * The shapes worth naming apart, in the order they are worth fixing.
 *
 * `realm prerequisite` comes first because it makes the others meaningless: a
 * surface owes a READER only where the decision is taken, and a panel built on
 * the wrong label shows zeros for ever.
 */
const imbalance = (d) => {
  if (SURFACES.some((s) => d[s]?.unavailable)) return 'realm prerequisite';
  if (!d.runtime?.has) return 'decision > explanation';
  if (d.agent?.has && !d.editor?.has) return 'agent > human';
  if (!d.editor?.has) return 'runtime > editor';
  if (!d.agent?.has) return 'human > agent';
  return null;
};

if (process.argv.includes('--list')) {
  const width = Math.max(...DECISIONS.map((d) => d.id.length));
  console.log(`${'decision'.padEnd(width)}  runtime editor agent  imbalance`);
  for (const d of DECISIONS) {
    const mark = (s) => (d[s]?.has ? '  ok   ' : ' owed  ');
    console.log(`${d.id.padEnd(width)} ${mark('runtime')}${mark('editor')}${mark('agent')} ${imbalance(d) ?? 'complete'}`);
  }
  for (const kind of ['owed', 'unavailable']) {
    const rows = owed.filter((o) => o.kind === kind);
    if (!rows.length) continue;
    console.log(`\n${kind} (${rows.length}):`);
    for (const o of rows) console.log(`  ${o.id} → ${o.surface}: ${o.why}`);
  }
}

if (skipped.length) {
  console.log(`check-decision-inventory: no editor checkout — ${skipped.length} citation(s) not judged:`
    + ` ${skipped.join(', ')}`);
}
if (problems.length) {
  console.error(`check-decision-inventory: ${problems.length} problem(s)`);
  for (const p of problems) console.error(`  ${p}`);
  console.error('\n  A citation that no longer finds its subject is a finding: either the decision moved'
    + '\n  and the entry follows it, or the entry was never true.');
  process.exit(1);
}
const counts = {};
for (const d of DECISIONS) counts[imbalance(d) ?? 'complete'] = (counts[imbalance(d) ?? 'complete'] ?? 0) + 1;
console.log(`check-decision-inventory: ${DECISIONS.length} decision(s), ${claimed} citation(s) hold — `
  + Object.entries(counts).map(([k, n]) => `${n} ${k}`).join(', ')
  + ` (${owed.length} owed surface(s); --list names them).`);