@pareto4/pp-core 1.13.0 → 1.18.0

package/pp-core/bin/lib/loop-gates.cjs

@@ -1,213 +0,0 @@
-"use strict";
-/**
- * Loop gate runner — the one owner of the generic `check.query` gate contract.
- *
- * Command surface: pp-tools loop run-gates <point> [--phase <N>] [--tier light|standard|heavy] [--query <q>] [--raw]
- *
- * Resolves the active hooks at <point> through the loop resolver (the same
- * owner `loop render-hooks` uses, so an unreadable config refuses here too),
- * then runs every active gate in registry order and applies the two-step gate
- * contract execute-phase states for `execute:wave:post` / `execute:post`:
- *
- *   Step 1 — did the check COMMAND succeed? (`pp-tools check <query> [<phase>]
- *   [<check.args>…] --raw` exits 0 with a JSON object). If not: `onError: halt` halts,
- *   `onError: skip` (or absent) warns and moves on; `block` is never read.
- *   Step 2 — read `block`. A blocking gate (`blocking: true`) halts on
- *   `block: true`; that halt is never bypassed by `onError`. An advisory gate
- *   (`blocking` not true) reports `block: true` or a non-empty `message` as an
- *   advisory and never halts. `block: false` with no message passes silently;
- *   a blocking gate that passes WITH a message (a note) passes with an `ℹ` line.
- *
- * `check.args` (optional) are literal tokens the gate declaration appends after
- * the phase — the gate's own policy, stated where the gate is declared (e.g.
- * `--stage plan`). `--query <q>` runs only the gates whose `check.query` is `q`,
- * so a host can run one gate in code beside a loop that handles the others.
- *
- * A gate this runner cannot run (no `check.query`, or a query that is not a
- * check name) halts when it is blocking and is reported when it is advisory:
- * a blocking gate is never passed having checked nothing.
- *
- * Output: the verdict JSON on stdout (`{ point, phase, halt, gates[], lines[] }`),
- * every line of `lines` also on stderr so a host capturing `$(…)` still shows
- * them, and exit 1 when `halt` is true. A host therefore writes
- * `X=$(pp_run loop run-gates <point> …) || exit 1` and the halt stops it.
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-const node_path_1 = __importDefault(require("node:path"));
-const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const ioMod = require("./io.cjs");
-const { output: coreOutput, error: coreError, ERROR_REASON } = ioMod;
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const loopResolverModule = require("./loop-resolver.cjs");
-const { resolveProjectLoopHooks } = loopResolverModule;
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const configLoaderModule = require("./config-loader.cjs");
-const { unreadableConfigFiles } = configLoaderModule;
-const phase_tier_cjs_1 = require("./phase-tier.cjs");
-/** A check name as `routeCheckCommand` accepts it (dotted or hyphenated); never an option or a path. */
-const CHECK_QUERY_RE = /^[a-z0-9][a-z0-9.-]*$/i;
-/** A declared `check.args` token: a flag or a plain word — never a path, a quote or a shell metacharacter. */
-const CHECK_ARG_RE = /^(?:--[a-z][a-z0-9-]*|[a-z0-9][a-z0-9._-]*)$/i;
-const CHECK_ARGS_MAX = 8;
-const CHECK_TIMEOUT_MS = 300_000;
-/** A check's operator message is relayed whole (line breaks kept), up to this many characters. */
-const MESSAGE_CAP = 16_000;
-function boundMessage(v) {
-    if (typeof v !== 'string')
-        return null;
-    const flat = v.replace(/\r\n?/g, '\n').replace(/[\u0000-\u0008\u000B-\u001F\u007F]+/g, ' ').trim();
-    if (flat === '')
-        return null;
-    return flat.length > MESSAGE_CAP ? `${flat.slice(0, MESSAGE_CAP)}…` : flat;
-}
-/** The declared `check.args`, or null when the declaration carries an argument this runner will not pass. */
-function declaredCheckArgs(check) {
-    const args = check ? check['args'] : undefined;
-    if (args === undefined)
-        return [];
-    if (!Array.isArray(args) || args.length > CHECK_ARGS_MAX)
-        return null;
-    return args.every((a) => typeof a === 'string' && CHECK_ARG_RE.test(a)) ? args : null;
-}
-/** Run `pp-tools check <query> [<phase>] [<args>…] --raw` in a child process (check handlers exit the process). */
-const defaultCheckRunner = (query, phase, cwd, checkArgs) => {
-    const tools = node_path_1.default.join(__dirname, '..', 'pp-tools.cjs');
-    const args = [tools, 'check', query, ...(phase ? [phase] : []), ...checkArgs, '--raw'];
-    const r = (0, shell_command_projection_cjs_1.execTool)(process.execPath, args, { cwd, timeout: CHECK_TIMEOUT_MS });
-    if (r.exitCode !== 0 || r.signal) {
-        const why = r.signal ? `killed by ${r.signal}` : `exit ${r.exitCode}`;
-        return { ok: false, result: null, error: `${why}${r.stderr ? `: ${r.stderr.split('\n')[0]}` : ''}` };
-    }
-    if (r.stdout === '')
-        return { ok: false, result: null, error: 'empty output' };
-    try {
-        const parsed = JSON.parse(r.stdout);
-        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
-            return { ok: false, result: null, error: 'output is not a JSON object' };
-        return { ok: true, result: parsed, error: null };
-    }
-    catch {
-        return { ok: false, result: null, error: 'output is not JSON' };
-    }
-};
-/**
- * Run every active gate at `point` (already resolved) under the two-step
- * contract. Pure apart from `runCheck`.
- */
-function runGates(point, phase, activeHooks, cwd, runCheck = defaultCheckRunner) {
-    const gates = [];
-    const lines = [];
-    let halt = false;
-    for (const h of activeHooks) {
-        if (h.kind !== 'gate')
-            continue;
-        const blocking = h.blocking === true;
-        const onError = typeof h.onError === 'string' ? h.onError : 'skip';
-        const check = h.check && typeof h.check === 'object' ? h.check : null;
-        const query = check && typeof check['query'] === 'string' ? check['query'] : null;
-        const checkArgs = declaredCheckArgs(check);
-        const run = { capId: h.capId, query, blocking, onError, outcome: 'pass', block: null, message: null };
-        if (query === null || !CHECK_QUERY_RE.test(query) || checkArgs === null) {
-            run.outcome = 'unrunnable';
-            run.message = query === null
-                ? 'the gate declares no check.query'
-                : checkArgs === null ? 'check.args is not a list of plain flags and words' : 'check.query is not a check name';
-            if (blocking) {
-                halt = true;
-                lines.push(`⛔ ${point} blocked: capability gate (${h.capId}) cannot be run (${run.message}). Fix the capability declaration before continuing.`);
-            }
-            else {
-                lines.push(`⚠ ${h.capId} advisory (${point}): gate not run — ${run.message}.`);
-            }
-            gates.push(run);
-            continue;
-        }
-        // Step 1 — did the check command itself succeed?
-        const r = runCheck(query, phase, cwd, checkArgs);
-        if (!r.ok || r.result === null) {
-            run.message = boundMessage(r.error) ?? 'command error';
-            if (onError === 'halt') {
-                run.outcome = 'error-halt';
-                halt = true;
-                lines.push(`⛔ ${point} blocked: gate check command failed (${h.capId}: check ${query}): ${run.message}. Resolve before continuing.`);
-            }
-            else {
-                run.outcome = 'error-skip';
-                lines.push(`⚠ ${point} gate check command failed (${h.capId}: check ${query}): ${run.message} — skipped (onError: ${onError}).`);
-            }
-            gates.push(run);
-            continue;
-        }
-        // Step 2 — read block (only reached when the command succeeded).
-        const block = r.result['block'] === true;
-        run.block = block;
-        run.message = boundMessage(r.result['message']) ?? boundMessage(r.result['reason']);
-        if (blocking && block) {
-            run.outcome = 'blocked';
-            halt = true;
-            lines.push(`⛔ ${point} blocked by capability gate (${h.capId}): ${run.message ?? `check ${query} reported block`}. Resolve before continuing.`);
-        }
-        else if (!blocking && (block || boundMessage(r.result['message']) !== null)) {
-            run.outcome = 'advisory';
-            lines.push(`⚠ ${h.capId} advisory (${point}): ${run.message ?? `check ${query} reported block`}`);
-        }
-        else {
-            run.outcome = 'pass';
-            const note = blocking ? boundMessage(r.result['message']) : null;
-            if (note !== null)
-                lines.push(`ℹ ${h.capId} (${point}): ${note}`);
-        }
-        gates.push(run);
-    }
-    return { point, phase, halt, gates, lines };
-}
-/**
- * `loop run-gates <point> [--phase <N>] [--tier <t>]`. Exit 1 on a halt or a
- * refusal; the verdict JSON is on stdout either way except on a refusal.
- */
-function cmdLoopRunGates(cwd, point, raw, options = {}) {
-    if (!point) {
-        coreError('loop run-gates requires a <point> argument (e.g. verify:post)', ERROR_REASON.USAGE);
-        return;
-    }
-    const phase = typeof options['phase'] === 'string' && options['phase'] !== '' ? options['phase'] : null;
-    const tierCli = typeof options['tier'] === 'string' && options['tier'] !== '' ? options['tier'] : null;
-    if (tierCli !== null && !['light', 'standard', 'heavy'].includes(tierCli)) {
-        coreError('--tier needs one of light, standard, heavy', ERROR_REASON.USAGE);
-        return;
-    }
-    const phaseTier = (phase !== null || tierCli !== null) && unreadableConfigFiles(cwd).length === 0
-        ? (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, phase, tierCli)
-        : null;
-    const outcome = resolveProjectLoopHooks(cwd, point, { phaseTier, what: `loop run-gates ${point}` });
-    if (!outcome.ok) {
-        coreError(outcome.message, outcome.reason === 'config_unreadable' ? ERROR_REASON.CONFIG_PARSE_FAILED : undefined);
-        return;
-    }
-    const onlyQuery = typeof options['query'] === 'string' && options['query'] !== '' ? options['query'] : null;
-    const hooks = onlyQuery === null
-        ? outcome.resolved.activeHooks
-        : outcome.resolved.activeHooks.filter((h) => {
-            const c = h.check && typeof h.check === 'object' ? h.check : null;
-            return c !== null && c['query'] === onlyQuery;
-        });
-    const verdict = runGates(point, phase, hooks, cwd);
-    if (verdict.lines.length > 0) {
-        try {
-            process.stderr.write(verdict.lines.join('\n') + '\n');
-        }
-        catch {
-            /* stderr closed */
-        }
-    }
-    coreOutput(verdict, raw);
-    if (verdict.halt)
-        process.exitCode = 1;
-}
-module.exports = {
-    runGates,
-    cmdLoopRunGates,
-};