@spexcode/spec-eval 0.6.5

package/dist/evaltab.d.ts

@@ -0,0 +1,98 @@
+import { type DriftIndex, type HistoryIndex } from '@spexcode/spec-core';
+import { loadSpecs } from '@spexcode/spec-core';
+import type { RemarkTrack, Issue } from './remarks.js';
+export type { RemarkTrack, Issue, Reply } from './remarks.js';
+import { type EvalNode, type ScenarioTestReference } from './scenarios.js';
+import { type Verdict, type EvidenceKind, type Retraction } from './sidecar.js';
+import { type StaleAxis } from './freshness.js';
+import { type ScenarioIndex } from './scenariofresh.js';
+export type EvidenceView = {
+    hash: string;
+    kind: EvidenceKind;
+    state: 'present' | 'miss';
+};
+export type RemarkView = {
+    rid: string;
+    ref: string;
+    by: string;
+    at: string;
+    body: string;
+    targetCodeSha: string;
+    resolved: boolean;
+    resolvedAt?: string;
+    resolvedBy?: string;
+    dangling: boolean;
+};
+export type EvalEntry = {
+    scenario: string;
+    expected: string;
+    codeSha: string;
+    evidence?: EvidenceView[];
+    blob: string | null;
+    blobKind?: EvidenceKind;
+    timelineBlob?: string;
+    evaluator?: string;
+    by?: string;
+    verdict?: Verdict;
+    ts: string;
+    fresh: boolean;
+    staleAxes: StaleAxis[];
+    freshnessDeferred?: true;
+    blobState: 'present' | 'miss' | 'none';
+    codeDrift?: {
+        file: string;
+        behind: number;
+    }[];
+    remarks?: RemarkView[];
+    thread?: Issue;
+    humanOk?: {
+        by: string;
+        ts: string;
+    };
+};
+export type DanglingTrack = {
+    scenario: string;
+    threadId: string;
+    thread: Issue;
+    remarks: RemarkView[];
+};
+export type ScenarioInfo = {
+    name: string;
+    expected: string;
+    tags?: string[];
+    test?: ScenarioTestReference;
+    code?: string[];
+};
+export type EvalTimeline = {
+    node: string;
+    hasEvalFile: boolean;
+    scenarios: ScenarioInfo[];
+    readings: EvalEntry[];
+    retractions: Retraction[];
+    dangling: DanglingTrack[];
+};
+export type EvalContext = {
+    root: string;
+    specs: Awaited<ReturnType<typeof loadSpecs>>;
+    idx: DriftIndex;
+    hidx: HistoryIndex;
+    scidx: ScenarioIndex;
+    ynodes: EvalNode[];
+    remarks: Map<string, RemarkTrack>;
+};
+export declare function evalContext(root: string, specs: Awaited<ReturnType<typeof loadSpecs>>, idx: DriftIndex, hidx: HistoryIndex, remarks?: Map<string, RemarkTrack>, ynodes?: EvalNode[]): Promise<EvalContext>;
+export declare function evalTimelines(ids: readonly string[], ctx?: EvalContext, opts?: {
+    order?: boolean;
+}): Promise<EvalTimeline[]>;
+export declare function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalTimeline>;
+export type BlobResult = {
+    ok: true;
+    bytes: Buffer;
+    mime: string;
+} | {
+    ok: false;
+    reason: 'invalid' | 'miss';
+    message: string;
+};
+export declare function readBlobByHash(hash: string, dir?: string): BlobResult;
+export declare function sniffBlobMime(b: Buffer): string;

package/dist/evaltab.js

@@ -0,0 +1,176 @@
+import { relative, dirname } from 'node:path';
+import { repoRoot, driftIndex, historyIndex, commitReachable } from '@spexcode/spec-core';
+import { loadSpecs } from '@spexcode/spec-core';
+import { evalRemarkTracks, trackKey } from './host.js';
+import { evalNodes, scenarioCodeAxis } from './scenarios.js';
+import { readSidecar, applyRetractions, evidenceOf, isJsonBlob, humanOkFor } from './sidecar.js';
+import { staleAxes, codeDrift, contentProbeFor, anchorProbeFor } from './freshness.js';
+import { scenarioIndex } from './scenariofresh.js';
+import { hasBlob, getBlob, MISS_BLOB } from './cache.js';
+function toRemarkView(rm, threadId, dangling) {
+    return {
+        rid: rm.rid,
+        ref: `${threadId}#${rm.rid}`,
+        by: rm.by, at: rm.at, body: rm.body,
+        targetCodeSha: rm.targetCodeSha ?? '',
+        resolved: !!rm.resolved,
+        ...(rm.resolvedAt ? { resolvedAt: rm.resolvedAt } : {}),
+        ...(rm.resolvedBy ? { resolvedBy: rm.resolvedBy } : {}),
+        dangling,
+    };
+}
+export async function evalContext(root, specs, idx, hidx, remarks, ynodes) {
+    const nodes = ynodes ?? evalNodes(root);
+    const scidx = await scenarioIndex(root, nodes.map((n) => n.evalPath));
+    return { root, specs, idx, hidx, scidx, ynodes: nodes, remarks: remarks ?? evalRemarkTracks() };
+}
+// @@@ one read, one batch - the freshness engine's Git work is immutable-object work, so it is owned ONCE
+// per read rather than once per reading. evalTimelines is the plural the graph build actually wants: it
+// plans every node's rows first (pure fs + in-memory projection), primes the content and anchor probes with
+// the WHOLE demand set, then assembles. Singular evalTimeline is the one-id case of the same path.
+// @@@ `order` skips the FRESHNESS pass, not the rows - a caller that only needs to know WHICH scenarios are
+// in play and in what sequence (identity, filed time, measured-or-blind) pays for none of the probes: on a
+// 415-node scope the freshness pass is 25s and 1476 git children, the rows themselves are milliseconds.
+// Rows returned this way carry `freshnessDeferred` INSTEAD of `fresh`/`staleAxes`, and evalReviewState
+// refuses them loudly — an order row can never be mistaken for a measured verdict.
+export async function evalTimelines(ids, ctx, opts = {}) {
+    const root = ctx?.root ?? repoRoot();
+    const ynodes = ctx?.ynodes ?? evalNodes(root);
+    const specs = ctx?.specs ?? await loadSpecs();
+    const idx = ctx?.idx ?? await driftIndex(root);
+    const hidx = ctx?.hidx ?? await historyIndex(root);
+    const scidx = ctx?.scidx ?? await scenarioIndex(root, ynodes.map((n) => n.evalPath));
+    const tracks = ctx?.remarks ?? evalRemarkTracks();
+    const probe = contentProbeFor(root);
+    const anchors = anchorProbeFor(root, idx);
+    const plans = ids.map((id) => {
+        const ynode = ynodes.find((n) => n.id === id);
+        if (!ynode)
+            return { id, codeEntries: [], rows: [], retractions: [], oks: [] };
+        const codeEntries = specs.find((s) => dirname(s.path) === relative(root, ynode.dir))?.codeEntries ?? [];
+        const byName = new Map(ynode.scenarios.map((s) => [s.name, s]));
+        const { readings, retractions, oks } = readSidecar(ynode.sidecarPath);
+        const rows = applyRetractions(readings, retractions).map((reading) => ({
+            reading, axis: scenarioCodeAxis(byName.get(reading.scenario)?.code, codeEntries),
+        }));
+        return { id, ynode, codeEntries, rows, retractions, oks };
+    });
+    // an order-only read stops HERE, before a single probe: the rows above are already the whole answer.
+    if (opts.order)
+        return plans.map((plan) => assembleTimeline(plan.id, plan.ynode, plan.rows, plan.retractions, plan.oks, {
+            idx, scidx, tracks, probe, anchors, order: true,
+        }));
+    // An off-history anchor is the only reading that needs a content verdict. Plan the population first so the
+    // probe can answer many anchor/HEAD pairs through bounded plural children instead of one child per anchor.
+    const contentDemands = plans.flatMap((plan) => plan.ynode
+        ? plan.rows.filter((row) => !commitReachable(idx, row.reading.codeSha))
+            .map((row) => ({ anchorSha: row.reading.codeSha, paths: row.axis.paths, evalPath: plan.ynode.evalPath }))
+        : []);
+    if (probe.primeMany)
+        await probe.primeMany(contentDemands);
+    else
+        await Promise.all(contentDemands.map((row) => probe.prime?.(row.anchorSha, [...row.paths], row.evalPath)));
+    await anchors.prime?.(plans.flatMap((plan) => plan.rows.map((row) => ({ sinceSha: row.reading.codeSha, entries: row.axis.entries }))));
+    // the primes above only RECORDED which eval.md blocks the assemble step will compare; one batched pair of
+    // children answers the whole read's worth, the same shape the anchor prime above already has.
+    await probe.primeBlocks?.();
+    return plans.map((plan) => assembleTimeline(plan.id, plan.ynode, plan.rows, plan.retractions, plan.oks, {
+        idx, scidx, tracks, probe, anchors,
+    }));
+}
+export async function evalTimeline(id, ctx) {
+    return (await evalTimelines([id], ctx))[0];
+}
+function assembleTimeline(id, ynode, rows, retractions, oks, { idx, scidx, tracks, probe, anchors, order }) {
+    if (!ynode)
+        return { node: id, hasEvalFile: false, scenarios: [], readings: [], retractions: [], dangling: [] };
+    const byName = new Map(ynode.scenarios.map((s) => [s.name, s]));
+    const remarksFor = (scenario) => tracks.get(trackKey(id, scenario))?.remarks ?? [];
+    const threadFor = (scenario) => tracks.get(trackKey(id, scenario))?.thread;
+    const scenarios = ynode.scenarios.map((s) => ({
+        name: s.name, expected: s.expected,
+        ...(s.tags?.length ? { tags: s.tags } : {}), ...(s.test ? { test: s.test } : {}),
+        ...(s.code?.length ? { code: s.code } : {}),
+    }));
+    const readings = [];
+    for (const { reading: r, axis } of rows) {
+        const sc = byName.get(r.scenario);
+        const axes = order ? [] : staleAxes(r, axis.entries, ynode.evalPath, idx, scidx, remarksFor(r.scenario).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt })), probe, sc, anchors);
+        const drift = !order && axes.includes('code') ? codeDrift(idx, r.codeSha, axis.entries, probe) : [];
+        const evidence = evidenceOf(r).map((e) => ({ hash: e.hash, kind: e.kind, state: hasBlob(e.hash) ? 'present' : 'miss' }));
+        const primary = evidence.find((e) => e.kind === 'video') ?? evidence[0];
+        const okRow = humanOkFor(oks, r.scenario, r.ts);
+        readings.push({
+            scenario: r.scenario,
+            expected: byName.get(r.scenario)?.expected ?? '',
+            codeSha: r.codeSha,
+            ...(evidence.length ? { evidence } : {}),
+            blob: primary?.hash ?? null,
+            ...(primary ? { blobKind: primary.kind } : {}),
+            ...(r.timelineBlob ? { timelineBlob: r.timelineBlob } : {}),
+            ...(r.evaluator ? { evaluator: r.evaluator } : {}),
+            ...(r.by ? { by: r.by } : {}),
+            ...(r.verdict ? { verdict: r.verdict } : {}),
+            ts: r.ts,
+            fresh: !order && axes.length === 0,
+            staleAxes: axes,
+            ...(order ? { freshnessDeferred: true } : {}),
+            ...(drift.length ? { codeDrift: drift } : {}),
+            blobState: primary ? primary.state : 'none',
+            ...(threadFor(r.scenario) ? { thread: threadFor(r.scenario) } : {}),
+            ...(okRow ? { humanOk: { by: okRow.by, ts: okRow.ts } } : {}),
+        });
+    }
+    readings.reverse();
+    const declared = new Set(ynode.scenarios.map((s) => s.name));
+    const dangling = [];
+    for (const [, track] of tracks) {
+        if (track.node !== id || !track.remarks.length)
+            continue;
+        const hosts = readings.filter((r) => r.scenario === track.scenario);
+        if (!hosts.length) {
+            if (!declared.has(track.scenario)) {
+                dangling.push({
+                    scenario: track.scenario, threadId: track.threadId, thread: track.thread,
+                    remarks: track.remarks.map((rm) => toRemarkView(rm, track.threadId, true)),
+                });
+            }
+            continue;
+        }
+        const latest = hosts[0];
+        for (const rm of track.remarks) {
+            const target = hosts.find((r) => r.codeSha === rm.targetCodeSha);
+            const host = target ?? latest;
+            (host.remarks ??= []).push(toRemarkView(rm, track.threadId, !target));
+        }
+    }
+    return { node: id, hasEvalFile: true, scenarios, readings, retractions: [...retractions].reverse(), dangling };
+}
+const HEX64 = /^[0-9a-f]{64}$/;
+export function readBlobByHash(hash, dir) {
+    if (!HEX64.test(hash))
+        return { ok: false, reason: 'invalid', message: 'bad evidence hash' };
+    const bytes = getBlob(hash, dir); // undefined dir → the live cache (cache.ts default); a temp dir in tests
+    if (!bytes)
+        return { ok: false, reason: 'miss', message: MISS_BLOB };
+    return { ok: true, bytes, mime: sniffBlobMime(bytes) };
+}
+export function sniffBlobMime(b) {
+    if (b.length >= 4 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47)
+        return 'image/png';
+    if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+        return 'image/jpeg';
+    if (b.length >= 4 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46)
+        return 'image/gif';
+    // WebM/Matroska begin with the EBML magic 1A 45 DF A3; disambiguate from a RIFF/WEBP image above.
+    if (b.length >= 4 && b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3)
+        return 'video/webm';
+    // ISO-BMFF (MP4/MOV): a `ftyp` box type at bytes 4..8, after its 4-byte size.
+    if (b.length >= 12 && b.toString('ascii', 4, 8) === 'ftyp')
+        return 'video/mp4';
+    if (b.length >= 12 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP')
+        return 'image/webp';
+    if (b.length && !b.includes(0))
+        return isJsonBlob(b) ? 'application/json' : 'text/plain; charset=utf-8';
+    return 'application/octet-stream';
+}

package/dist/filing.d.ts

@@ -0,0 +1,16 @@
+import { type Reading } from './sidecar.js';
+export type FileResult = {
+    ok: true;
+    reading: Reading;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function fileHumanReading(nodeId: string, input: {
+    scenario: string;
+    status: 'pass' | 'fail';
+    note?: string;
+    transcript?: string;
+    by?: string;
+}): FileResult;
+export declare function evalReadingFiler(nodeId: string, scenario: string, root?: string): string | null;

package/dist/filing.js

@@ -0,0 +1,36 @@
+import { repoRoot, headSha } from '@spexcode/spec-core';
+import { evalNodes, resolveEvalNode, scenarioHash } from './scenarios.js';
+import { appendReading, readReadings, isJsonBlob } from './sidecar.js';
+import { putBlob } from './cache.js';
+export function fileHumanReading(nodeId, input) {
+    const root = repoRoot();
+    const res = resolveEvalNode(evalNodes(root), nodeId);
+    if (!res.ok)
+        return { ok: false, error: res.error };
+    const node = res.node;
+    const sc = node.scenarios.find((s) => s.name === input.scenario);
+    if (!sc)
+        return { ok: false, error: `'${nodeId}' has no scenario '${input.scenario}'` };
+    if (input.status !== 'pass' && input.status !== 'fail')
+        return { ok: false, error: 'status must be pass or fail' };
+    const buf = input.transcript ? Buffer.from(input.transcript) : null;
+    const blob = buf ? putBlob(buf) : null;
+    const reading = {
+        scenario: sc.name,
+        codeSha: headSha(root),
+        scenarioHash: scenarioHash(sc),
+        ...(blob ? { evidence: [{ hash: blob, kind: (buf && isJsonBlob(buf) ? 'data' : 'transcript') }] } : {}),
+        ...(input.by ? { by: input.by } : {}),
+        verdict: { status: input.status, ...(input.note ? { note: input.note } : {}) },
+        ts: new Date().toISOString(),
+    };
+    appendReading(node.sidecarPath, reading);
+    return { ok: true, reading };
+}
+export function evalReadingFiler(nodeId, scenario, root = repoRoot()) {
+    const res = resolveEvalNode(evalNodes(root), nodeId);
+    if (!res.ok)
+        return null;
+    const forScenario = readReadings(res.node.sidecarPath).filter((r) => r.scenario === scenario);
+    return forScenario.length ? forScenario[forScenario.length - 1].by ?? null : null;
+}

package/dist/freshness.d.ts

@@ -0,0 +1,48 @@
+import { type DriftIndex } from '@spexcode/spec-core';
+import { type RelationEntry } from '@spexcode/spec-core';
+import type { Reading } from './sidecar.js';
+import { type Scenario, type ScenarioCodeAxisSource } from './scenarios.js';
+import { type ScenarioIndex } from './scenariofresh.js';
+export type StaleAxis = 'code' | 'scenario' | 'remark' | 'anchor';
+export type ContentProbeDemand = {
+    anchorSha: string;
+    paths: readonly string[];
+    evalPath: string;
+};
+export type ContentProbe = {
+    changed(anchorSha: string, path: string): boolean | null;
+    canTestify(anchorSha: string): boolean;
+    scenarioDiffers(anchorSha: string, evalPath: string, scenario: string): boolean;
+    inAnchorPast(anchorSha: string, commit: string): boolean;
+    prime?(anchorSha: string, paths: string[], evalPath: string): Promise<void>;
+    primeMany?(demands: readonly ContentProbeDemand[]): Promise<void>;
+    primeBlocks?(): Promise<void>;
+};
+export declare function freshnessCacheSize(root?: string): number;
+export declare function anchorVerdictCacheSize(root?: string): number;
+export declare function contentProbeFor(root: string): ContentProbe;
+export type AnchorProbe = {
+    hit(sinceSha: string, path: string, selectors: readonly string[]): boolean | null;
+    prime?(demands: readonly AnchorDemand[]): Promise<void>;
+};
+export type AnchorDemand = {
+    sinceSha: string;
+    entries: readonly RelationEntry[];
+};
+export declare function anchorProbeFor(root: string, idx: DriftIndex): AnchorProbe;
+export declare function anchorProblems(root: string, entries: readonly RelationEntry[]): string[];
+export type RemarkSignal = {
+    resolved: boolean;
+    resolvedAt?: string;
+};
+export declare function remarkStale(reading: {
+    ts: string;
+}, remarks: RemarkSignal[]): boolean;
+export declare function changedSince(idx: DriftIndex, sinceSha: string, path: string, probe?: ContentProbe): boolean;
+export declare function codeDrift(idx: DriftIndex, sinceSha: string, codeAxis: ScenarioCodeAxisSource, probe?: ContentProbe): {
+    file: string;
+    behind: number;
+}[];
+export declare function staleAxes(reading: Reading, codeAxis: ScenarioCodeAxisSource, evalPath: string, didx: DriftIndex, scIdx: ScenarioIndex, remarks?: RemarkSignal[], probe?: ContentProbe, current?: Scenario, // the scenario's CURRENT declaration (undefined = gone from eval.md) — the hash compare's other side
+anchors?: AnchorProbe): StaleAxis[];
+export declare function isStale(reading: Reading, codeAxis: ScenarioCodeAxisSource, evalPath: string, didx: DriftIndex, scIdx: ScenarioIndex, remarks?: RemarkSignal[], probe?: ContentProbe, current?: Scenario, anchors?: AnchorProbe): boolean;