@spexcode/spec-eval 0.6.5

package/dist/host.d.ts

@@ -0,0 +1,46 @@
+import type { RemarkTrack } from './remarks.js';
+export type EvalHost = {
+    loadConfig?: (root: string) => any;
+    trackedSourceFiles?: (root: string, roots: string[], policy: any) => string[];
+    stripRefSigil?: (value: string) => string;
+    commitTrunkData?: (path: string, message: string) => 'committed' | 'no-op' | 'not-primary';
+    apiBase?: () => Promise<string>;
+};
+export type ReviewIdentity = {
+    id: string;
+    node: string | null;
+    branch: string | null;
+    label: string;
+};
+export type ReviewPayload = {
+    id: string;
+    node: string | null;
+    branch: string | null;
+    label: string;
+    ahead: number;
+    dirtyNonRuntime: number;
+    diff: import('@spexcode/spec-core').ReviewDiffFile[];
+    gates: {
+        conflictsWithMain: boolean;
+        lint: {
+            errorCount: number;
+            warningCount: number;
+        };
+    };
+    proposal: {
+        kind: string | null;
+        note: string | null;
+    };
+};
+export type EvalHostPort = EvalHost & {
+    reviewIdentity: (id: string) => ReviewIdentity | null;
+    reviewPayload: (id: string) => Promise<ReviewPayload | null>;
+    loadEvalRemarkTracks?: () => Map<string, RemarkTrack>;
+};
+export declare function setEvalRemarkTracks(loader: () => Map<string, RemarkTrack>): void;
+export declare function setEvalHost(next: EvalHost): void;
+export declare function evalHost(): EvalHost;
+export declare function requireEvalHost<K extends keyof EvalHost>(field: K): NonNullable<EvalHost[K]>;
+export declare function evalRemarkTracks(): Map<string, RemarkTrack>;
+export declare function evalRemarkSourceFingerprint(): string;
+export declare const trackKey: (node: string, scenario: string) => string;

package/dist/host.js

@@ -0,0 +1,53 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+let services = {};
+let remarks = () => new Map();
+export function setEvalRemarkTracks(loader) {
+    remarks = loader;
+}
+export function setEvalHost(next) { services = { ...services, ...next }; }
+export function evalHost() { return services; }
+// CLI-backed commands must fail at the capability boundary, rather than letting an absent
+// service turn into an unrelated TypeError or an empty result. Remark reads are the one
+// deliberate standalone downgrade and stay on evalRemarkTracks() below.
+export function requireEvalHost(field) {
+    const value = services[field];
+    if (value == null)
+        throw new Error(`spec-eval host is not configured: ${String(field)}`);
+    return value;
+}
+export function evalRemarkTracks() {
+    return remarks();
+}
+// The eval engine fingerprints the remark input even when no CLI host is installed. It deliberately hashes
+// bytes, not issue semantics; the CLI host remains the sole owner of parsing and joining remark tracks.
+export function evalRemarkSourceFingerprint() {
+    const root = process.env.SPEXCODE_ISSUES_DIR;
+    if (!root)
+        return '';
+    const files = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries.sort()) {
+            const path = join(dir, name);
+            try {
+                if (statSync(path).isDirectory())
+                    walk(path);
+                else
+                    files.push(`${path}\0${readFileSync(path).toString('base64')}`);
+            }
+            catch {
+                files.push(`${path}\0<unreadable>`);
+            }
+        }
+    };
+    walk(root);
+    return files.join('\0');
+}
+export const trackKey = (node, scenario) => `${node} · ${scenario}`;

package/dist/humanok.d.ts

@@ -0,0 +1,11 @@
+import { type HumanOk } from './sidecar.js';
+export type OkResult = {
+    ok: true;
+    humanOk: HumanOk;
+    already: boolean;
+    landed: 'committed' | 'uncommitted';
+} | {
+    ok: false;
+    error: string;
+};
+export declare function fileHumanOk(nodeId: string, scenario: string, by: string): OkResult;

package/dist/humanok.js

@@ -0,0 +1,27 @@
+import { relative } from 'node:path';
+import { repoRoot } from '@spexcode/spec-core';
+import { requireEvalHost } from './host.js';
+import { evalNodes, resolveEvalNode } from './scenarios.js';
+import { readReadings, readSidecar, appendHumanOk, humanOkFor } from './sidecar.js';
+export function fileHumanOk(nodeId, scenario, by) {
+    const root = repoRoot();
+    const res = resolveEvalNode(evalNodes(root), nodeId);
+    if (!res.ok)
+        return { ok: false, error: res.error };
+    const node = res.node;
+    if (!node.scenarios.some((s) => s.name === scenario) &&
+        !readSidecar(node.sidecarPath).readings.some((r) => r.scenario === scenario))
+        return { ok: false, error: `'${node.id}' has no scenario '${scenario}'` };
+    const forScenario = readReadings(node.sidecarPath).filter((r) => r.scenario === scenario);
+    if (!forScenario.length)
+        return { ok: false, error: `'${node.id}' scenario '${scenario}' has no effective eval — nothing to ok` };
+    const latest = forScenario[forScenario.length - 1];
+    const existing = humanOkFor(readSidecar(node.sidecarPath).oks, scenario, latest.ts);
+    if (existing)
+        return { ok: true, humanOk: existing, already: true, landed: 'committed' };
+    const row = { kind: 'human-ok', scenario, okTs: latest.ts, okSha: latest.codeSha, by, ts: new Date().toISOString() };
+    appendHumanOk(node.sidecarPath, row);
+    const commit = requireEvalHost('commitTrunkData');
+    const landed = commit(relative(root, node.sidecarPath), `eval(${node.id}): human-ok '${scenario}' @ ${latest.ts} by ${by}`);
+    return { ok: true, humanOk: row, already: false, landed: landed === 'not-primary' ? 'uncommitted' : 'committed' };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './sessioneval.js';
+export * from './evaltab.js';
+export * from './scenarios.js';
+export * from './host.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './sessioneval.js';
+export * from './evaltab.js';
+export * from './scenarios.js';
+export * from './host.js';

package/dist/remarks.d.ts

@@ -0,0 +1,31 @@
+export type Reply = {
+    by: string;
+    at: string;
+    body: string;
+    rid?: string;
+    targetCodeSha?: string;
+    resolved?: boolean;
+    resolvedAt?: string;
+    resolvedBy?: string;
+};
+export type Issue = {
+    id: string;
+    store: string;
+    concern: string;
+    by: string;
+    status: string;
+    nodes: string[];
+    created: string;
+    body: string;
+    replies: Reply[];
+    evidence: string[];
+    labels: unknown[];
+    url?: string;
+};
+export type RemarkTrack = {
+    threadId: string;
+    node: string;
+    scenario: string;
+    thread: Issue;
+    remarks: Reply[];
+};

package/dist/remarks.js

@@ -0,0 +1 @@
+export {};

package/dist/scenariofresh.d.ts

@@ -0,0 +1,13 @@
+export type ScenarioIndex = Map<string, Map<string, string[]>>;
+export declare function scenarioIndex(root: string, evalPaths: string[]): Promise<ScenarioIndex>;
+export declare function scenarioCacheStats(): {
+    heads: number;
+    roots: number;
+};
+export declare function scenarioChangeCommits(idx: ScenarioIndex, evalPath: string, scenario: string): string[];
+export declare function primeScenarioBlocks(root: string, demands: readonly {
+    rev: string;
+    path: string;
+}[]): Promise<void>;
+export declare function primeScenarioBlocksAt(root: string, revs: string[], path: string): Promise<void>;
+export declare function scenarioBlocksAt(root: string, rev: string, path: string): Map<string, string> | null;

package/dist/scenariofresh.js

@@ -0,0 +1,303 @@
+import { spawn } from 'node:child_process';
+import { batchBlobTexts, batchRevisionOids, git, gitA, gitTry, headSha } from '@spexcode/spec-core';
+import { parseScenarios } from './scenarios.js';
+import { rootSlots, touchRoot as touchRootLru } from '@spexcode/spec-core';
+const RS = '\x1e';
+function blockContent(src) {
+    const m = new Map();
+    for (const s of parseScenarios(src)) {
+        m.set(s.name, JSON.stringify({ d: s.description, e: s.expected }));
+    }
+    return m;
+}
+const ZERO = '0'.repeat(40);
+const EMPTY = new Map();
+const blockByOid = new Map();
+async function fileChains(root, wanted) {
+    const chains = new Map();
+    const alias = new Map();
+    const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log',
+        '--raw', '--no-abbrev', '--full-history', '-M', `--format=${RS}%H`, '--', '*eval.md', '*yatsu.md']); // dead-words-ok: archived pathspec — immutable pre-rename history is read under its archived name
+    for (const rec of out.split(RS)) {
+        const nl = rec.indexOf('\n');
+        if (nl < 0)
+            continue;
+        const hash = rec.slice(0, nl);
+        if (!hash)
+            continue;
+        for (const line of rec.slice(nl + 1).split('\n')) {
+            if (line[0] !== ':')
+                continue; // `:<oldmode> <newmode> <oldoid> <newoid> <status>\t<path>[\t<path2>]`
+            const tab = line.indexOf('\t');
+            if (tab < 0)
+                continue;
+            const meta = line.slice(1, tab).split(' ');
+            const oid = meta[3], rename = meta[4][0] === 'R' || meta[4][0] === 'C';
+            const paths = line.slice(tab + 1).split('\t');
+            const to = rename ? paths[1] : paths[0];
+            let head = alias.get(to);
+            if (head === undefined) {
+                head = to;
+                alias.set(to, to);
+            }
+            let arr = chains.get(head);
+            if (!arr) {
+                arr = [];
+                chains.set(head, arr);
+            }
+            arr.push({ hash, oid });
+            if (rename && paths[0] !== to) {
+                alias.set(paths[0], head);
+                alias.delete(to);
+            }
+        }
+    }
+    for (const k of [...chains.keys()])
+        if (!wanted.has(k))
+            chains.delete(k);
+    return chains;
+}
+function scenarioCommits(chain) {
+    const commits = new Map();
+    const push = (name, hash) => { const a = commits.get(name); if (a)
+        a.push(hash);
+    else
+        commits.set(name, [hash]); };
+    const real = chain.filter((v) => v.oid !== ZERO);
+    for (let i = 0; i < real.length; i++) {
+        const cur = blockByOid.get(real[i].oid) ?? EMPTY;
+        const older = i + 1 < real.length ? (blockByOid.get(real[i + 1].oid) ?? EMPTY) : EMPTY;
+        for (const name of new Set([...cur.keys(), ...older.keys()])) {
+            if (cur.get(name) !== older.get(name))
+                push(name, real[i].hash);
+        }
+    }
+    return commits;
+}
+// read MANY blobs in ONE `git cat-file --batch` process (vs one `git show` per blob). Feeds the OIDs on
+// stdin, parses the `<oid> <type> <size>\n<payload>\n` records byte-accurately (size is bytes; blobs are
+// UTF-8). A `<oid> missing` line yields no entry. Env-stripped like git.ts's helpers (a stray GIT_DIR would
+// misroute repo discovery); kept here beside its only caller — a general git-seam primitive if a second
+// caller ever wants one.
+function catFileBatch(root, oids) {
+    const out = new Map();
+    if (!oids.length)
+        return Promise.resolve(out);
+    return new Promise((resolve, reject) => {
+        const env = { ...process.env };
+        delete env.GIT_DIR;
+        delete env.GIT_WORK_TREE;
+        delete env.GIT_INDEX_FILE;
+        delete env.GIT_OBJECT_DIRECTORY;
+        const p = spawn('git', ['-C', root, 'cat-file', '--batch'], { env, timeout: Number(process.env.SPEXCODE_GIT_TIMEOUT_MS || 120000), killSignal: 'SIGKILL' });
+        const chunks = [];
+        p.stdout.on('data', (c) => chunks.push(c));
+        p.on('error', reject);
+        p.on('close', (_code, signal) => {
+            // a child that never exited was SIGKILLed at the timeout (a hung git must not pin this promise —
+            // same bound as git.ts's helpers); warn loudly and parse whatever arrived.
+            if (signal === 'SIGKILL')
+                console.warn(`spec-eval: git cat-file --batch killed after timeout — child never exited`);
+            const buf = Buffer.concat(chunks);
+            let i = 0;
+            while (i < buf.length) {
+                const nl = buf.indexOf(0x0a, i);
+                if (nl < 0)
+                    break;
+                const header = buf.toString('utf8', i, nl);
+                i = nl + 1;
+                if (header.endsWith(' missing'))
+                    continue; // unknown OID — no payload follows
+                const size = Number(header.slice(header.lastIndexOf(' ') + 1));
+                if (!Number.isFinite(size))
+                    break;
+                out.set(header.slice(0, header.indexOf(' ')), buf.toString('utf8', i, i + size));
+                i += size + 1; // payload + its trailing newline
+            }
+            resolve(out);
+        });
+        p.stdin.on('error', () => { });
+        p.stdin.write(oids.join('\n') + '\n');
+        p.stdin.end();
+    });
+}
+async function build(root, evalPaths) {
+    const chains = await fileChains(root, new Set(evalPaths));
+    const need = new Set();
+    for (const chain of chains.values())
+        for (const v of chain)
+            if (v.oid !== ZERO && !blockByOid.has(v.oid))
+                need.add(v.oid);
+    if (need.size) {
+        const blobs = await catFileBatch(root, [...need]);
+        for (const [oid, src] of blobs)
+            blockByOid.set(oid, blockContent(src));
+    }
+    const idx = new Map();
+    for (const p of evalPaths)
+        idx.set(p, scenarioCommits(chains.get(p) ?? []));
+    return idx;
+}
+const SLOTS = rootSlots(process.env.SPEXCODE_SCENARIO_CACHE_ROOTS, 16);
+const cache = new Map();
+const roots = new Map();
+function touchRoot(root, head) {
+    touchRootLru(roots, cache, root, head, SLOTS);
+}
+export function scenarioIndex(root, evalPaths) {
+    let head;
+    try {
+        head = headSha(root);
+    }
+    catch {
+        return build(root, evalPaths);
+    }
+    touchRoot(root, head);
+    const hit = cache.get(head);
+    if (hit) {
+        cache.delete(head);
+        cache.set(head, hit);
+        return hit;
+    }
+    const p = build(root, evalPaths);
+    p.catch(() => cache.delete(head));
+    cache.set(head, p);
+    while (cache.size > SLOTS)
+        cache.delete(cache.keys().next().value);
+    return p;
+}
+export function scenarioCacheStats() {
+    return { heads: cache.size, roots: roots.size };
+}
+export function scenarioChangeCommits(idx, evalPath, scenario) {
+    return idx.get(evalPath)?.get(scenario) ?? [];
+}
+const FULL_SHA = /^[0-9a-f]{40}$/;
+const oidMemo = new Map();
+function oidAt(root, rev, path) {
+    const resolve = () => { try {
+        return git(['-C', root, 'rev-parse', `${rev}:${path}`]).trim();
+    }
+    catch {
+        return '';
+    } };
+    if (!FULL_SHA.test(rev))
+        return resolve();
+    const k = `${root}\x1f${rev}\x1f${path}`;
+    const hit = oidMemo.get(k);
+    if (hit !== undefined) {
+        oidMemo.delete(k);
+        oidMemo.set(k, hit);
+        return hit;
+    }
+    const v = resolve();
+    oidMemo.set(k, v);
+    if (oidMemo.size > 4096)
+        oidMemo.delete(oidMemo.keys().next().value);
+    return v;
+}
+// @@@ the memo holds SETTLED oids, so concurrent askers need a flight to join - primes run concurrently
+// across the whole scope, and every one of them missed the memo while the first child was still running:
+// measured on adopter-a's 415-node scope, 2695 `rev-parse` children resolved 1212 distinct (rev, path) pairs.
+// `rev:path` under a full sha names an immutable object, so joining answers the same question; the LRU
+// write still happens once, on settle, exactly as the sync path does it.
+const oidFlight = new Map();
+async function oidAtAsync(root, rev, path) {
+    if (!FULL_SHA.test(rev))
+        return (await gitTry(['-C', root, 'rev-parse', `${rev}:${path}`])).stdout.trim();
+    const k = `${root}\x1f${rev}\x1f${path}`;
+    const hit = oidMemo.get(k);
+    if (hit !== undefined) {
+        oidMemo.delete(k);
+        oidMemo.set(k, hit);
+        return hit;
+    }
+    const joined = oidFlight.get(k);
+    if (joined)
+        return joined;
+    const run = async () => {
+        const result = await gitTry(['-C', root, 'rev-parse', `${rev}:${path}`]);
+        const oid = result.ok ? result.stdout.trim() : '';
+        oidMemo.set(k, oid);
+        if (oidMemo.size > 4096)
+            oidMemo.delete(oidMemo.keys().next().value);
+        return oid;
+    };
+    const flight = run().finally(() => { if (oidFlight.get(k) === flight)
+        oidFlight.delete(k); });
+    oidFlight.set(k, flight);
+    return flight;
+}
+// @@@ the PLURAL prime, mirroring the anchor probe's - a caller hands over every (rev, path) its whole read
+// will ask about and TWO children answer them all: `cat-file --batch-check` for the object ids, then
+// `cat-file --batch` for the blobs. The singular form below is one demand's worth of the same thing, kept
+// for callers that genuinely learn their demand one at a time. Priming one at a time is what this replaces:
+// on adopter-a's 415-node scope it forked 1212 `rev-parse` children plus a `cat-file` each, and the batch
+// answers the identical set — same oids, same blocks, same verdicts, two children.
+export async function primeScenarioBlocks(root, demands) {
+    const wanted = new Map();
+    for (const d of demands) {
+        if (!FULL_SHA.test(d.rev) || !d.path)
+            continue; // a symbolic rev is never memoized, so it can't ride a batch
+        const k = `${root}\x1f${d.rev}\x1f${d.path}`;
+        if (!oidMemo.has(k) && !wanted.has(k))
+            wanted.set(k, d);
+    }
+    if (!wanted.size)
+        return;
+    const keys = [...wanted.keys()];
+    const rows = [...wanted.values()];
+    const oids = await batchRevisionOids(root, rows.map((d) => `${d.rev}:${d.path}`));
+    oids.forEach((oid, i) => {
+        oidMemo.set(keys[i], oid ?? '');
+        if (oidMemo.size > 4096)
+            oidMemo.delete(oidMemo.keys().next().value);
+    });
+    const missing = [...new Set(oids.filter((o) => !!o && !blockByOid.has(o)))];
+    if (!missing.length)
+        return;
+    const texts = await batchBlobTexts(root, missing);
+    for (const [oid, src] of texts)
+        if (src)
+            blockByOid.set(oid, blockContent(src));
+}
+// the blob read needs the same flight as the oid lookup above it: an oid is content, so two primes that
+// resolved the same one must not each read it.
+const blockFlight = new Map();
+export async function primeScenarioBlocksAt(root, revs, path) {
+    for (const rev of revs) {
+        const oid = await oidAtAsync(root, rev, path);
+        if (!oid || blockByOid.has(oid))
+            continue;
+        const joined = blockFlight.get(oid);
+        if (joined) {
+            await joined;
+            continue;
+        }
+        const run = async () => {
+            const src = await gitA(['-C', root, 'cat-file', 'blob', oid]); // dead-words-ok: git plumbing
+            if (src)
+                blockByOid.set(oid, blockContent(src));
+        };
+        const flight = run().finally(() => { if (blockFlight.get(oid) === flight)
+            blockFlight.delete(oid); });
+        blockFlight.set(oid, flight);
+        await flight;
+    }
+}
+export function scenarioBlocksAt(root, rev, path) {
+    const oid = oidAt(root, rev, path);
+    if (!oid)
+        return null;
+    const hit = blockByOid.get(oid);
+    if (hit)
+        return hit;
+    try {
+        const m = blockContent(git(['-C', root, 'cat-file', 'blob', oid])); // dead-words-ok: git plumbing — 'blob' is git's object type, not our vocabulary
+        blockByOid.set(oid, m);
+        return m;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/scenarios.d.ts

@@ -0,0 +1,99 @@
+import { type RelationEntry } from '@spexcode/spec-core';
+export declare const EVAL_FILE = "eval.md";
+export declare const SIDECAR_FILE = "evals.ndjson";
+export type ScenarioTestReference = {
+    path: string;
+    name?: string;
+};
+export type Scenario = {
+    name: string;
+    description: string;
+    expected: string;
+    tags?: string[];
+    test?: ScenarioTestReference;
+    code?: string[];
+    related?: string[];
+};
+export declare const SCENARIO_PROJECTION = "spex.eval.scenario-index";
+export declare const SCENARIO_SCHEMA_VERSION = 1;
+export type ScenarioSemanticRow = {
+    node: string;
+    name: string;
+    description: string;
+    expected: string;
+    scenarioHash: string;
+    code: RelationEntry[];
+    related: RelationEntry[];
+    tags: string[];
+};
+export type ScenarioMeasurementRow = {
+    test: ScenarioTestReference | null;
+};
+export type ScenarioProjectionRow = {
+    semantic: ScenarioSemanticRow;
+    measurement: ScenarioMeasurementRow;
+};
+export type ScenarioProjectionNode = {
+    id: string;
+    code: RelationEntry[];
+    related: RelationEntry[];
+};
+export type ScenarioProjectionProvenance = {
+    head: string | null;
+    treeSha: string | null;
+};
+export type ScenarioProjection = {
+    projection: typeof SCENARIO_PROJECTION;
+    schemaVersion: typeof SCENARIO_SCHEMA_VERSION;
+    provenance: ScenarioProjectionProvenance;
+    nodes: ScenarioProjectionNode[];
+    semanticIndexHash: string;
+    fullIndexHash: string;
+    planningIndexHash: string;
+    rows: ScenarioProjectionRow[];
+};
+export type EvalNode = {
+    id: string;
+    dir: string;
+    evalPath: string;
+    sidecarPath: string;
+    scenarios: Scenario[];
+    evalSource?: string;
+    specSource?: string;
+};
+export declare function scenarioHash(s: Pick<Scenario, 'description' | 'expected'>): string;
+export type ScenarioCodeAxis = {
+    entries: RelationEntry[];
+    paths: string[];
+    problems: string[];
+};
+export type ScenarioCodeAxisSource = readonly string[] | readonly RelationEntry[];
+export declare function scenarioCodeAxis(scenarioCode: readonly string[] | undefined, nodeCode?: ScenarioCodeAxisSource): ScenarioCodeAxis;
+export declare function parseScenarios(src: string): Scenario[];
+export declare function scenarioProjection(nodes: readonly Pick<EvalNode, 'id' | 'scenarios' | 'evalSource' | 'specSource'>[], provenance?: Partial<ScenarioProjectionProvenance>): ScenarioProjection;
+export declare function validateScenarios(src: string, tagLibrary?: string[], pathRoot?: string): string[];
+export type ScenarioMeasurementMetadataMutation = {
+    scenario: string;
+    insert: {
+        test: string | {
+            path: string;
+            name: string;
+        };
+    };
+} | {
+    scenario: string;
+    delete: 'test';
+};
+export declare function writeScenarioMeasurementMetadata(source: string, request: unknown): string;
+export declare function evalNodes(root: string): EvalNode[];
+export declare function evalNodesAt(root: string, tip: string): EvalNode[];
+export declare function evalNodesAsync(root: string): Promise<EvalNode[]>;
+export type EvalResolution<T> = {
+    ok: true;
+    node: T;
+} | {
+    ok: false;
+    ambiguous: boolean;
+    error: string;
+};
+export declare function resolveEvalNode<T extends Pick<EvalNode, 'id' | 'dir'>>(nodes: T[], ref: string): EvalResolution<T>;