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.

13.5 KB
Raw Blame
#!/usr/bin/env node
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  contract-inventory.mjs — what Estella's runtime contract facts are,
 *        who authors each, and what would notice if one changed.
 *
 * `EsEventOut` shipped for as long as it existed with no word count of its own,
 * no compile-time check and no term in any digest. That was not thin test
 * coverage — the ABI compatibility system did not know a fact lived there. The
 * two are different severities and nothing could tell them apart, because
 * nothing enumerated the facts.
 *
 * This enumerates them. It is DESCRIPTIVE on purpose: no authority moves, no
 * artifact is generated from here. First answer what exists, then decide what is
 * worth canonicalising — the reverse builds a central schema and then goes
 * looking for things to put in it.
 *
 * Two kinds of finding, and the second is the one that keeps this honest:
 *
 *   - A CLAIM that no longer holds. Every citation carries a probe, so an entry
 *     pointing at a fact that has moved is red rather than stale documentation.
 *   - GROUND with no claim over it. A generated artifact no fact projects, or a
 *     `C++ contract:` pin no fact names, is a fact nobody wrote down. This is
 *     the same comparison `check-verification-authority` makes, and it is why a
 *     longer list would not have done.
 *
 * Sabotaged in four directions before it was trusted, each red on its own line
 * and nothing else: a probe pointed at a moved fact, a verification that was
 * also a projection, an unattributed `*.generated.*`, and a `C++ contract:` pin
 * no fact named.
 *
 *   node tools/contract-inventory.mjs [--json]
 */
import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { execFileSync } from 'node:child_process';
import { FACTS, NOT_CONTRACT, RE_EXPORTS } from './lib/contractFacts.mjs';

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const JSON_OUT = process.argv.includes('--json');
const findings = [];
const notes = [];

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

/** Every file under a directory, so a directory author can be probed. */
function walk(dir, out = []) {
    for (const name of readdirSync(path.join(ROOT, dir))) {
        const child = `${dir}/${name}`;
        if (statSync(path.join(ROOT, child)).isDirectory()) walk(child, out);
        else out.push(child);
    }
    return out;
}

/**
 * Does the fact still live where the entry says? A citation is only worth
 * having if it fails when the thing it points at moves.
 */
function probeHolds(cite) {
    const at = path.join(ROOT, cite.path);
    if (!existsSync(at)) return 'no such path';
    if (cite.dir) {
        const files = walk(cite.path);
        if (!files.length) return 'directory is empty';
        for (const f of files) {
            try {
                if (cite.probe.test(read(f))) return null;
            } catch { /* binary or unreadable; the next file may match */ }
        }
        return `no file under it matches ${cite.probe}`;
    }
    return cite.probe.test(read(cite.path)) ? null : `does not match ${cite.probe}`;
}

/**
 * Authority, projection and verification are three roles, and the third has to
 * be INDEPENDENT of the first two or the green means nothing. A file that is
 * both a projection and the verification of the same fact is a generator being
 * asked whether it generated correctly.
 */
function checkRoleSeparation(fact) {
    const projected = new Set(fact.projections);
    for (const v of fact.verification) {
        if (projected.has(v.path)) {
            findings.push(`${fact.id}: ${v.path} is cited as BOTH a projection and a`
                + ' verification. A derivation cannot verify itself.');
        }
    }
}

/** Computed, never declared: the status is what the citations add up to. */
function statusOf(fact) {
    const semantic = fact.authors.filter((a) => a.kind === 'semantic');
    const impl = fact.authors.filter((a) => a.kind === 'implementation');
    const verified = fact.verification.length > 0;
    if (impl.length > 1) {
        return verified ? 'multi-implementation-differential' : 'multi-implementation-unbound';
    }
    if (semantic.length > 1) {
        return verified ? 'multi-author-machine-verified' : 'multi-author-unbound';
    }
    if (fact.digest) return 'single-author-covered';
    return verified ? 'single-author-verified' : 'single-author-unverified';
}

const RED_STATUS = new Set(['multi-author-unbound', 'multi-implementation-unbound', 'single-author-unverified']);

const report = [];
for (const fact of FACTS) {
    for (const [role, cites] of [['author', fact.authors], ['verification', fact.verification]]) {
        for (const cite of cites) {
            const why = probeHolds(cite);
            if (why) findings.push(`${fact.id}: ${role} ${cite.path} — ${why}`);
        }
    }
    for (const p of fact.projections) {
        if (!existsSync(path.join(ROOT, p))) findings.push(`${fact.id}: projection ${p} — no such path`);
    }
    if (fact.digest) {
        const why = probeHolds(fact.digest);
        if (why) findings.push(`${fact.id}: digest ${fact.digest.name} at ${fact.digest.path} — ${why}`);
    }
    checkRoleSeparation(fact);

    const status = statusOf(fact);
    if (RED_STATUS.has(status) && !fact.owed) {
        findings.push(`${fact.id}: ${status} — more than one author and nothing compares them,`
            + ' and no `owed` says why that is accepted.');
    }
    // The debt is paid the day the gate says so, not the day someone remembers.
    // Keyed on a FIELD, not on how the sentence was worded: a rule that greps its
    // own prose is dodged by a rephrase, which is the failure it exists to stop.
    if (fact.owedUntil === 'digest' && fact.digest) {
        findings.push(`${fact.id}: its gap says it closes when a digest covers the fact, and`
            + ` one does now (${fact.digest.name}). Rewrite or delete \`owed\` — a gap that`
            + ' reads as open after it closed is worse than none.');
    }
    if (fact.owedUntil && !fact.owed) {
        findings.push(`${fact.id}: declares owedUntil with no \`owed\` saying what is missing.`);
    }
    report.push({ ...fact, status });
}

// ── Ground: every generated artifact belongs to a fact ────────────────────────
const tracked = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8' })
    .split('\n').filter(Boolean)
    .filter((f) => !/^(third_party|build)\//.test(f));

const GENERATED_NAME = /\.generated\.|\/generated\//;
const DECLARES_GENERATED = /auto-generated|GENERATED by|@generated|generatedBy|DO NOT EDIT|do not edit/i;
const generated = tracked.filter((f) => {
    if (!/\.(ts|tsx|js|mjs|c|h|hpp|cpp|json|d\.ts)$/.test(f)) return false;
    if (GENERATED_NAME.test(f)) return true;
    try {
        return DECLARES_GENERATED.test(read(f).slice(0, 400));
    } catch {
        return false;
    }
});

const projected = new Set(FACTS.flatMap((f) => f.projections));
for (const g of generated) {
    if (projected.has(g) || NOT_CONTRACT[g]) continue;
    findings.push(`GROUND: ${g} is generated, and no fact projects it. Either it derives`
        + ' from an authority (add it) or it is not a contract (say so in NOT_CONTRACT).');
}
for (const [p, why] of Object.entries(NOT_CONTRACT)) {
    if (!existsSync(path.join(ROOT, p))) findings.push(`NOT_CONTRACT names ${p}, which is gone — ${why}`);
}

/**
 * A derivation of an authority and of NOTHING ELSE — least of all of the
 * machine that ran the generator. `constants.generated.ts` shipped citing
 * `D:/estella/...`: every rebuild elsewhere rewrote all six lines, and a
 * regenerate-and-compare over it would have reported the host, not the code.
 */
const MACHINE_PATH = /(?:^|[^A-Za-z0-9_])(?:[A-Za-z]:[\\/](?:Users|home|dev|estella)|\/(?:Users|home)\/[A-Za-z0-9._-]+\/)/;
for (const g of generated) {
    let text;
    try {
        text = read(g);
    } catch {
        continue;
    }
    const line = text.split('\n').findIndex((l) => MACHINE_PATH.test(l));
    if (line >= 0) {
        findings.push(`GROUND: ${g}:${line + 1} carries an absolute path from the machine that`
            + ' generated it. A generated artifact must come out the same on every checkout,'
            + ' or its diff reports the host.');
    }
}

// ── Ground: every hand-copied cross-language pin belongs to a fact ────────────
const PIN_FILE = 'sdk/tests/cpp-contract.test.ts';
if (existsSync(path.join(ROOT, PIN_FILE))) {
    const src = read(PIN_FILE);
    const titles = [...src.matchAll(/describe\('C\+\+ contract: ([^']*?) \(([^)]*)\)'/g)].map((m) => m[1]);
    const probes = FACTS.flatMap((f) => f.verification.filter((v) => v.path === PIN_FILE).map((v) => v.probe));
    for (const title of titles) {
        if (!probes.some((p) => p.test(title))) {
            findings.push(`GROUND: "${PIN_FILE}" pins "${title}", and no fact names that pin.`
                + ' A constant hand-copied across the boundary is a fact whether or not it is written down.');
        }
    }
    notes.push(`${titles.length} cross-language pin(s) in ${PIN_FILE}, each claimed by a fact.`);

    /**
     * Every side a verifier COMPARES has to be a node this list explains. The
     * ledger said uiBaseLayer had one author while the pin read a second,
     * hand-written declaration in the SDK — a fact with two authors, recorded
     * as one, because nothing asked what the verifier was reading.
     */
    const declared = new Set(FACTS.flatMap((f) => [
        ...f.authors.map((a) => a.path),
        ...f.projections,
        ...f.verification.flatMap((v) => v.compares ?? []),
    ]).concat(Object.keys(RE_EXPORTS)));
    const reads = readsOf(PIN_FILE);
    // A pin that resolves to no repo file is a checker that cannot see, not a
    // tree with nothing to answer for: both walks below would read clean on any
    // tree, which is how a separator this host spells differently stayed quiet.
    if (reads.length === 0) {
        findings.push(`GROUND: ${PIN_FILE} names no repo file this run can resolve — the`
            + ' two checks below have nothing to walk, and would pass on any tree.');
    }
    for (const rel of reads) {
        if (declared.has(rel)) continue;
        findings.push(`GROUND: ${PIN_FILE} reads ${rel}, and no fact names it — as an author, as`
            + ' a projection, or in the `compares` of the verification that reads it.');
    }
    notes.push(`${reads.length} repo file(s) read by ${PIN_FILE}, each one a node this list `
        + 'explains.');
    // An excuse nobody uses is an excuse that stops being true.
    for (const [rel, why] of Object.entries(RE_EXPORTS)) {
        if (!reads.includes(rel)) {
            findings.push(`RE_EXPORTS names ${rel} (${why}), which ${PIN_FILE} no longer reads.`);
        }
    }
} else {
    findings.push(`GROUND: ${PIN_FILE} is gone; the cross-language pins it held are now unclaimed.`);
}

/** Repo files a source names: an import, or a path handed to a reader. Resolved
 *  against the roots this repo's test helpers use, and joined with `path.posix`
 *  because the answer is held against `git ls-files`: a backslash matches
 *  nothing there, so on Windows the pin read as naming NO file at all — every
 *  re-export a stale excuse, and the ground check walking an empty list. */
function readsOf(rel) {
    const text = read(rel);
    const bases = [path.posix.dirname(rel), '', 'src/esengine'];
    const out = new Set();
    for (const m of text.matchAll(/'([^'\n]+)'/g)) {
        const lit = m[1];
        if (!lit.includes('/') || lit.startsWith('/')) continue;
        for (const base of bases) {
            for (const ext of ['', '.ts', '.hpp', '.cpp']) {
                const at = path.posix.normalize(path.posix.join(base, lit) + ext);
                if (tracked.includes(at)) out.add(at);
            }
        }
    }
    return [...out];
}

// ── Say it ───────────────────────────────────────────────────────────────────
if (JSON_OUT) {
    const shape = report.map((f) => ({
        id: f.id,
        what: f.what,
        surface: f.surface,
        status: f.status,
        authors: f.authors.map((a) => ({ path: a.path, kind: a.kind })),
        projections: f.projections,
        verification: f.verification.map((v) => ({ path: v.path, how: v.how })),
        digest: f.digest ? f.digest.name : null,
        owed: f.owed ?? null,
    }));
    console.log(JSON.stringify({ facts: shape, findings }, null, 2));
} else {
    const width = Math.max(...report.map((f) => f.id.length));
    for (const f of report) {
        const digest = f.digest ? f.digest.name : '—';
        console.log(`  ${f.id.padEnd(width)}  ${f.status.padEnd(33)} digest: ${digest}`);
    }
    const owed = report.filter((f) => f.owed);
    if (owed.length) {
        console.log(`\n${owed.length} declared gap(s) — work, not permission:`);
        for (const f of owed) console.log(`  ${f.id}: ${f.owed}`);
    }
    for (const n of notes) console.log(`\n${n}`);
    console.log(`\n${generated.length} generated artifact(s), each attributed.`);
}

if (findings.length) {
    console.error(`\ncontract-inventory: ${findings.length} finding(s).`);
    for (const f of findings) console.error(`  ${f}`);
    process.exit(1);
}
if (!JSON_OUT) console.log(`\ncontract-inventory: ${FACTS.length} fact(s), every claim held against the tree.`);