spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-eval/dist/sidecar.d.ts

@@ -0,0 +1,55 @@
+export type Verdict = {
+    status: 'pass' | 'fail';
+    note?: string;
+};
+export type EvidenceKind = 'image' | 'transcript' | 'video' | 'data';
+export type Evidence = {
+    hash: string;
+    kind: EvidenceKind;
+};
+export type Reading = {
+    scenario: string;
+    codeSha: string;
+    scenarioHash?: string;
+    evidence?: Evidence[];
+    blob?: string | null;
+    blobKind?: EvidenceKind;
+    timelineBlob?: string;
+    evaluator?: string;
+    by?: string;
+    verdict?: Verdict;
+    ts: string;
+};
+export declare function evidenceOf(r: {
+    evidence?: Evidence[];
+    blob?: string | null;
+    blobKind?: EvidenceKind;
+}): Evidence[];
+export declare function isJsonBlob(b: Buffer): boolean;
+export type Retraction = {
+    retracts: string;
+    scenario: string;
+    note?: string;
+    by?: string;
+    ts: string;
+};
+export type HumanOk = {
+    kind: 'human-ok';
+    scenario: string;
+    okTs: string;
+    okSha: string;
+    by: string;
+    ts: string;
+};
+export declare function readSidecar(sidecarPath: string): {
+    readings: Reading[];
+    retractions: Retraction[];
+    oks: HumanOk[];
+};
+export declare function applyRetractions(readings: Reading[], retractions: Retraction[]): Reading[];
+export declare function readReadings(sidecarPath: string): Reading[];
+export declare function appendReading(sidecarPath: string, r: Reading): void;
+export declare function appendRetraction(sidecarPath: string, r: Retraction): void;
+export declare function appendHumanOk(sidecarPath: string, r: HumanOk): void;
+export declare function humanOkFor(oks: HumanOk[], scenario: string, readingTs: string): HumanOk | null;
+export declare function latestPerScenario(readings: Reading[]): Map<string, Reading>;

package/node_modules/@spexcode/spec-eval/dist/sidecar.js

@@ -0,0 +1,82 @@
+import { readFileSync, appendFileSync, existsSync } from 'node:fs';
+export function evidenceOf(r) {
+    if (r.evidence?.length)
+        return r.evidence;
+    if (r.blob)
+        return [{ hash: r.blob, kind: r.blobKind ?? 'image' }];
+    return [];
+}
+export function isJsonBlob(b) {
+    if (!b.length || b.includes(0))
+        return false; // empty or binary → not JSON text
+    if (b.length > 4_000_000)
+        return false; // don't parse an unbounded blob just to sniff a type
+    const s = b.toString('utf8').trim();
+    const open = s[0], close = s[s.length - 1];
+    if (!((open === '{' && close === '}') || (open === '[' && close === ']')))
+        return false;
+    try {
+        const v = JSON.parse(s);
+        return v !== null && typeof v === 'object';
+    }
+    catch {
+        return false;
+    }
+}
+export function readSidecar(sidecarPath) {
+    const readings = [];
+    const retractions = [];
+    const oks = [];
+    if (!existsSync(sidecarPath))
+        return { readings, retractions, oks };
+    for (const line of readFileSync(sidecarPath, 'utf8').split('\n')) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const r = JSON.parse(t);
+            if (!r || typeof r.scenario !== 'string')
+                continue;
+            if (typeof r.retracts === 'string')
+                retractions.push(r);
+            else if (r.kind === 'human-ok' && typeof r.okTs === 'string')
+                oks.push(r);
+            else if (typeof r.codeSha === 'string')
+                readings.push(r);
+        }
+        catch { /* Keep earlier events readable after an incomplete append. */ }
+    }
+    return { readings, retractions, oks };
+}
+export function applyRetractions(readings, retractions) {
+    if (!retractions.length)
+        return readings;
+    const gone = new Set(retractions.map((x) => `${x.scenario}\0${x.retracts}`));
+    return readings.filter((r) => !gone.has(`${r.scenario}\0${r.ts}`));
+}
+export function readReadings(sidecarPath) {
+    const { readings, retractions } = readSidecar(sidecarPath);
+    return applyRetractions(readings, retractions);
+}
+export function appendReading(sidecarPath, r) {
+    appendFileSync(sidecarPath, JSON.stringify(r) + '\n');
+}
+export function appendRetraction(sidecarPath, r) {
+    appendFileSync(sidecarPath, JSON.stringify(r) + '\n');
+}
+export function appendHumanOk(sidecarPath, r) {
+    appendFileSync(sidecarPath, JSON.stringify(r) + '\n');
+}
+export function humanOkFor(oks, scenario, readingTs) {
+    let hit = null;
+    for (const o of oks)
+        if (o.scenario === scenario && o.okTs === readingTs)
+            hit = o;
+    return hit;
+}
+export function latestPerScenario(readings) {
+    const m = new Map();
+    for (const r of readings)
+        m.set(r.scenario, r); // later lines overwrite earlier → last wins
+    return m;
+}

package/node_modules/@spexcode/spec-eval/dist/timeline.d.ts

@@ -0,0 +1,25 @@
+export type TimelineEvent = {
+    at: number;
+    step: string;
+    node?: string;
+};
+export type StepTimeline = {
+    v: 2;
+    axis: string;
+    events: TimelineEvent[];
+};
+export type LegacyTimelineEvent = {
+    tMs: number;
+    step: string;
+    node?: string;
+};
+export type LegacyStepTimeline = {
+    v: 1;
+    events: LegacyTimelineEvent[];
+};
+export declare function validateTimeline(raw: unknown): string[];
+export declare function normalizeTimeline(raw: unknown): {
+    axis: string;
+    events: TimelineEvent[];
+};
+export declare function stepAt(events: TimelineEvent[], pos: number): TimelineEvent | null;

package/node_modules/@spexcode/spec-eval/dist/timeline.js

@@ -0,0 +1,65 @@
+const V2_EVENT_KEYS = new Set(['at', 'step', 'node']);
+const V1_EVENT_KEYS = new Set(['tMs', 'step', 'node']);
+export function validateTimeline(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return ['timeline must be a JSON object { v, axis, events }'];
+    const o = raw;
+    if (o.v !== 1 && o.v !== 2)
+        return ['`v` must be 1 (legacy time axis) or 2 (axis-tagged)'];
+    const errs = [];
+    const v2 = o.v === 2;
+    const posKey = v2 ? 'at' : 'tMs';
+    const rootKeys = v2 ? new Set(['v', 'axis', 'events']) : new Set(['v', 'events']);
+    const evKeys = v2 ? V2_EVENT_KEYS : V1_EVENT_KEYS;
+    for (const k of Object.keys(o))
+        if (!rootKeys.has(k))
+            errs.push(`unknown field \`${k}\` (allowed: ${[...rootKeys].join(', ')})`);
+    if (v2 && (typeof o.axis !== 'string' || !o.axis.trim()))
+        errs.push('`axis` must be a non-empty string (e.g. time, frame, line, index)');
+    if (!Array.isArray(o.events)) {
+        errs.push('`events` must be an array');
+        return errs;
+    }
+    let prev = -Infinity;
+    o.events.forEach((e, i) => {
+        if (typeof e !== 'object' || e === null || Array.isArray(e)) {
+            errs.push(`events[${i}] must be an object`);
+            return;
+        }
+        const ev = e;
+        for (const k of Object.keys(ev))
+            if (!evKeys.has(k))
+                errs.push(`events[${i}]: unknown field \`${k}\` (allowed: ${[...evKeys].join(', ')})`);
+        const pos = ev[posKey];
+        if (typeof pos !== 'number' || !Number.isFinite(pos) || pos < 0) {
+            errs.push(`events[${i}].${posKey} must be a finite number ≥ 0`);
+        }
+        else {
+            if (pos < prev)
+                errs.push(`events[${i}].${posKey} is out of order (the list is ordered by position)`);
+            prev = pos;
+        }
+        if (typeof ev.step !== 'string' || !ev.step.trim())
+            errs.push(`events[${i}].step must be a non-empty string`);
+        if (ev.node !== undefined && (typeof ev.node !== 'string' || !ev.node.trim()))
+            errs.push(`events[${i}].node must be a non-empty string when present`);
+    });
+    return errs;
+}
+export function normalizeTimeline(raw) {
+    const o = (raw ?? {});
+    const events = Array.isArray(o.events) ? o.events : [];
+    if (o.v === 1)
+        return { axis: 'time', events: events.map((e) => ({ at: e.tMs, step: e.step, ...(e.node ? { node: e.node } : {}) })) };
+    return { axis: typeof o.axis === 'string' ? o.axis : 'time', events: events.map((e) => ({ at: e.at, step: e.step, ...(e.node ? { node: e.node } : {}) })) };
+}
+export function stepAt(events, pos) {
+    let hit = null;
+    for (const e of events) {
+        if (e.at <= pos)
+            hit = e;
+        else
+            break;
+    }
+    return hit;
+}

package/node_modules/@spexcode/spec-eval/dist/ui-path.d.ts

@@ -0,0 +1 @@
+export declare const isUiPath: (p: string) => boolean;

package/node_modules/@spexcode/spec-eval/dist/ui-path.js

@@ -0,0 +1,2 @@
+const UI_FILE = /\.(jsx|tsx|vue|svelte|css)$/;
+export const isUiPath = (p) => UI_FILE.test(p) || p.includes('spec-dashboard/');

package/node_modules/@spexcode/spec-eval/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@spexcode/spec-eval",
+  "version": "0.6.5",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./sessioneval": "./dist/sessioneval.js",
+    "./evaltab": "./dist/evaltab.js",
+    "./cli": "./dist/cli.js",
+    "./cache": "./dist/cache.js",
+    "./filing": "./dist/filing.js",
+    "./humanok": "./dist/humanok.js",
+    "./scenarios": "./dist/scenarios.js",
+    "./host": "./dist/host.js",
+    "./remarks": "./dist/remarks.js",
+    "./package.json": "./package.json"
+  },
+  "files": ["dist"],
+  "description": "The eval/loss engine \u2014 eval.md declares scenarios, a flat evals.ndjson sidecar records readings (a second git-as-database axis), freshness compares each reading's stored scenario-contract hash and git ancestry on its governed code, and evidence lives content-addressed under the shared git common dir. `spex eval add|ls|scenario ls|lint|retract|clean`.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../scripts/release-publish.mjs --from-package-publish",
+    "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@spexcode/spec-core": "0.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/node_modules/@spexcode/spec-forge/dist/cache.d.ts

@@ -0,0 +1,29 @@
+import type { ForgeDriver, ForgeIssue, ForgePR } from './port.js';
+import { type NodeLinks } from './links.js';
+export type ForgeDelta = {
+    kind: 'issue';
+    issue: ForgeIssue;
+} | {
+    kind: 'pr';
+    pr: ForgePR;
+} | {
+    kind: 'remove';
+    target: 'issue' | 'pr';
+    number: number;
+};
+export declare class ForgeCache {
+    private issues;
+    private prs;
+    private revision;
+    apply(delta: ForgeDelta): void;
+    reconcile(driver: ForgeDriver): Promise<void>;
+    applyIssues(issues: ForgeIssue[]): void;
+    setPRs(prs: ForgePR[]): void;
+    view(nodeIds: string[]): NodeLinks[];
+    state(): {
+        issues: ForgeIssue[];
+        prs: ForgePR[];
+    };
+    stateRevision(): number;
+    private set;
+}

package/node_modules/@spexcode/spec-forge/dist/cache.js

@@ -0,0 +1,59 @@
+import { resolveLinks } from './links.js';
+function sameMap(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [number, value] of a)
+        if (!b.has(number) || JSON.stringify(value) !== JSON.stringify(b.get(number)))
+            return false;
+    return true;
+}
+export class ForgeCache {
+    issues = new Map();
+    prs = new Map();
+    revision = 0;
+    apply(delta) {
+        if (delta.kind === 'issue')
+            this.set(this.issues, delta.issue);
+        else if (delta.kind === 'pr')
+            this.set(this.prs, delta.pr);
+        else {
+            const target = delta.target === 'issue' ? this.issues : this.prs;
+            if (target.delete(delta.number))
+                this.revision++;
+        }
+    }
+    async reconcile(driver) {
+        const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()]);
+        const nextIssues = new Map(issues.map((i) => [i.number, i]));
+        const nextPRs = new Map(prs.map((p) => [p.number, p]));
+        if (!sameMap(this.issues, nextIssues) || !sameMap(this.prs, nextPRs))
+            this.revision++;
+        this.issues = nextIssues;
+        this.prs = nextPRs;
+    }
+    applyIssues(issues) {
+        for (const i of issues)
+            this.set(this.issues, i);
+    }
+    setPRs(prs) {
+        const next = new Map(prs.map((p) => [p.number, p]));
+        if (!sameMap(this.prs, next))
+            this.revision++;
+        this.prs = next;
+    }
+    view(nodeIds) {
+        return resolveLinks([...this.issues.values()], [...this.prs.values()], nodeIds);
+    }
+    state() {
+        return { issues: [...this.issues.values()], prs: [...this.prs.values()] };
+    }
+    stateRevision() {
+        return this.revision;
+    }
+    set(target, value) {
+        if (JSON.stringify(target.get(value.number)) !== JSON.stringify(value)) {
+            target.set(value.number, value);
+            this.revision++;
+        }
+    }
+}

package/node_modules/@spexcode/spec-forge/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runIssueLinks(args: string[]): Promise<number>;

package/node_modules/@spexcode/spec-forge/dist/cli.js

@@ -0,0 +1,100 @@
+import { loadSpecs } from '@spexcode/spec-core';
+import { FORGE_DRIVERS, forgeDriverFor, resolveForgeHost } from './drivers.js';
+import { resolveLinks } from './links.js';
+import { resolveEvalPending } from './needs-eval.js';
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+const has = (args, name) => args.includes(`--${name}`);
+async function readForge(args) {
+    const host = flag(args, 'store') ?? resolveForgeHost();
+    const driver = forgeDriverFor(host);
+    if (!driver) {
+        console.error(`spex issue links: unknown --store '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`);
+        return null;
+    }
+    const nodeIds = (await loadSpecs()).map((s) => s.id);
+    const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()]);
+    return { driver, nodeIds, issues, prs };
+}
+function render(links) {
+    const out = [];
+    for (const n of links) {
+        out.push(`\n${n.node}`);
+        if (n.issues.length) {
+            out.push('  issues:');
+            for (const i of n.issues)
+                out.push(`    #${i.number} ${i.state}  ${i.title}  (via ${i.via})  ${i.url}`);
+        }
+        if (n.prs.length) {
+            out.push('  prs:');
+            for (const p of n.prs)
+                out.push(`    #${p.number} ${p.state}  ${p.title}  ${p.headRefName}  ${p.url}`);
+        }
+    }
+    return out.join('\n');
+}
+async function links(args) {
+    const forge = await readForge(args);
+    if (!forge)
+        return 2;
+    const { driver, nodeIds, issues, prs } = forge;
+    let resolved = resolveLinks(issues, prs, nodeIds);
+    const only = flag(args, 'node');
+    if (only) {
+        if (!nodeIds.includes(only)) {
+            console.error(`spex issue links: no such node '${only}'`);
+            return 1;
+        }
+        resolved = resolved.filter((n) => n.node === only);
+    }
+    if (has(args, 'json')) {
+        console.log(JSON.stringify(resolved, null, 2));
+        return 0;
+    }
+    const nIssues = resolved.reduce((a, n) => a + n.issues.length, 0);
+    const nPRs = resolved.reduce((a, n) => a + n.prs.length, 0);
+    console.log(`spec-forge · ${driver.host} · ${resolved.length} linked node(s) · ${nIssues} issue(s), ${nPRs} pr(s)` +
+        ` · traced ${issues.length} issue(s), ${prs.length} pr(s)`);
+    if (resolved.length)
+        console.log(render(resolved));
+    return 0;
+}
+function renderPending(pending) {
+    const out = [];
+    for (const n of pending) {
+        out.push(`\n${n.node}`);
+        for (const i of n.pending)
+            out.push(`    #${i.number} ${i.state}  ${i.title}  (via ${i.via})  ${i.url}`);
+    }
+    return out.join('\n');
+}
+async function evalPending(args) {
+    const forge = await readForge(args);
+    if (!forge)
+        return 2;
+    const { driver, nodeIds, issues, prs } = forge;
+    let resolved = resolveEvalPending(issues, prs, nodeIds);
+    const only = flag(args, 'node');
+    if (only) {
+        if (!nodeIds.includes(only)) {
+            console.error(`spex issue links: no such node '${only}'`);
+            return 1;
+        }
+        resolved = resolved.filter((n) => n.node === only);
+    }
+    if (has(args, 'json')) {
+        console.log(JSON.stringify(resolved, null, 2));
+        return 0;
+    }
+    const nPending = resolved.reduce((a, n) => a + n.pending.length, 0);
+    console.log(`spec-forge · ${driver.host} · ${resolved.length} node(s) with eval pending · ${nPending} issue(s)` +
+        ` · traced ${issues.length} issue(s), ${prs.length} pr(s)`);
+    if (resolved.length)
+        console.log(renderPending(resolved));
+    return 0;
+}
+export async function runIssueLinks(args) {
+    return has(args, 'pending') ? evalPending(args) : links(args);
+}

package/node_modules/@spexcode/spec-forge/dist/drivers/github.d.ts

@@ -0,0 +1,2 @@
+import type { ForgeDriver } from '../port.js';
+export declare const githubDriver: ForgeDriver;

package/node_modules/@spexcode/spec-forge/dist/drivers/github.js

@@ -0,0 +1,116 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+// maxBuffer is raised above the 1MB default: a busy repo's issue/PR JSON can exceed it
+async function gh(args) {
+    const { stdout } = await run('gh', args, { maxBuffer: 16 * 1024 * 1024 });
+    return JSON.parse(stdout);
+}
+export const githubDriver = {
+    host: 'github',
+    // fetch open and closed in separate `--limit 200` windows and merge, so a flood of closed issues can't crowd the open set out of one shared `--state all` limit
+    async listIssues() {
+        const list = (state) => gh(['issue', 'list', '--state', state, '--limit', '200', '--json', 'number,title,body,url,state,labels,author,createdAt,comments']);
+        const [open, closed] = await Promise.all([list('open'), list('closed')]);
+        return [...open, ...closed].map((r) => ({
+            number: r.number,
+            title: r.title,
+            body: r.body ?? '',
+            url: r.url,
+            state: (r.state || '').toLowerCase(),
+            labels: forgeLabels(r.labels),
+            author: r.author?.login ?? '',
+            createdAt: r.createdAt ?? '',
+            comments: (r.comments ?? []).map((c) => ({ author: c.author?.login ?? '', createdAt: c.createdAt ?? '', body: c.body ?? '' })),
+        }));
+    },
+    async listIssuesSince(sinceISO) {
+        const out = [];
+        for (let page = 1; page <= 20; page++) {
+            const rows = await gh(['api', `repos/{owner}/{repo}/issues?state=all&since=${encodeURIComponent(sinceISO)}&per_page=100&page=${page}`]);
+            out.push(...rows);
+            if (rows.length < 100)
+                break;
+        }
+        return Promise.all(out.filter((r) => !r.pull_request).map(async (r) => ({
+            number: r.number,
+            title: r.title,
+            body: r.body ?? '',
+            url: r.html_url,
+            state: (r.state || '').toLowerCase(),
+            labels: forgeLabels(r.labels),
+            author: r.user?.login ?? '',
+            createdAt: r.created_at ?? '',
+            comments: r.comments > 0 ? await listComments(r.number) : [],
+        })));
+    },
+    async listPRs() {
+        const base = ['pr', 'list', '--state', 'open', '--limit', '200', '--json'];
+        const fields = 'number,title,url,state,headRefName';
+        let rows;
+        try {
+            rows = await gh([...base, `${fields},closingIssuesReferences`]);
+        }
+        catch (err) {
+            if (!isUnknownFieldError(err))
+                throw err;
+            warnNoTransitiveOnce();
+            rows = await gh([...base, fields]);
+        }
+        return rows.map((r) => ({
+            number: r.number,
+            title: r.title,
+            url: r.url,
+            state: r.state,
+            headRefName: r.headRefName,
+            closesIssues: (r.closingIssuesReferences ?? []).map((c) => c.number),
+        }));
+    },
+    async createIssue({ title, body }) {
+        const { stdout } = await run('gh', ['issue', 'create', '--title', title, '--body', body], { maxBuffer: 1024 * 1024 });
+        const url = stdout.trim().split('\n').pop() ?? '';
+        const number = parseInt(url.split('/').pop() ?? '', 10);
+        if (!url.startsWith('http') || !Number.isFinite(number))
+            throw new Error(`gh issue create returned an unexpected result: ${stdout.trim()}`);
+        return { number, url };
+    },
+    async createComment({ number, body }) {
+        const { stdout } = await run('gh', ['issue', 'comment', String(number), '--body', body], { maxBuffer: 1024 * 1024 });
+        const url = stdout.trim().split('\n').pop() ?? '';
+        if (!url.startsWith('http'))
+            throw new Error(`gh issue comment returned an unexpected result: ${stdout.trim()}`);
+        return { url };
+    },
+    // the lifecycle write verb (see port.ts). `gh issue close` does not reliably print a permalink, so read
+    // the issue URL back through gh's JSON surface after the close succeeds.
+    async closeIssue({ number }) {
+        await run('gh', ['issue', 'close', String(number)], { maxBuffer: 1024 * 1024 });
+        const r = await gh(['issue', 'view', String(number), '--json', 'url']);
+        if (!r.url?.startsWith('http'))
+            throw new Error(`gh issue view returned an unexpected url after close: ${JSON.stringify(r)}`);
+        return { url: r.url };
+    },
+};
+function forgeLabels(labels) {
+    return (labels ?? []).flatMap((label) => {
+        const name = typeof label === 'string' ? label : label.name ?? '';
+        return name ? [{ name, ...(typeof label === 'string' || !label.color ? {} : { color: label.color }) }] : [];
+    });
+}
+async function listComments(number) {
+    const rows = await gh(['api', `repos/{owner}/{repo}/issues/${number}/comments?per_page=100`]);
+    return rows.map((c) => ({ author: c.user?.login ?? '', createdAt: c.created_at ?? '', body: c.body ?? '' }));
+}
+function isUnknownFieldError(err) {
+    const e = err;
+    const text = `${e?.stderr ?? ''}\n${e?.message ?? ''}`;
+    return /unknown json field/i.test(text);
+}
+let warnedNoTransitive = false;
+function warnNoTransitiveOnce() {
+    if (warnedNoTransitive)
+        return;
+    warnedNoTransitive = true;
+    console.warn('spec-forge: this `gh` is too old for `closingIssuesReferences` — transitive issue↔PR links are ' +
+        'disabled (branch + `Spec:` marker links still work). Upgrade `gh` to restore them.');
+}

package/node_modules/@spexcode/spec-forge/dist/drivers/gitlab.d.ts

@@ -0,0 +1,7 @@
+import type { ForgeDriver } from '../port.js';
+export declare function parseRemote(remote: string): {
+    base: string;
+    host: string;
+    project: string;
+} | null;
+export declare const gitlabDriver: ForgeDriver;