@spexcode/spec-eval 0.6.5

package/dist/sessioneval.d.ts

@@ -0,0 +1,307 @@
+import { type ReviewDiffFile } from '@spexcode/spec-core';
+import { loadSpecs } from '@spexcode/spec-core';
+import { type AnchorHit, type RelationEntry } from '@spexcode/spec-core';
+import { type EvalEntry, type EvalTimeline, type ScenarioInfo } from './evaltab.js';
+import { type Scenario } from './scenarios.js';
+import { type EvalHostPort } from './host.js';
+export type { EvalHostPort } from './host.js';
+export declare function setSessionEvalHost(next: EvalHostPort): void;
+export declare function sessionEvalHost(): EvalHostPort;
+type ScoreState = 'pass' | 'fail' | 'stalePass' | 'staleFail' | 'empty' | null;
+export type ScenarioImpactReason = 'code' | 'contract' | 'measurement';
+export type SessionScenarioInfo = ScenarioInfo & {
+    impact: ScenarioImpactReason[];
+};
+export type SessionImpactSelectorHit = AnchorHit & {
+    path: string;
+};
+export type SessionImpactScenarioDelta = {
+    kind: 'added' | 'removed' | 'modified' | 'unchanged';
+    semantic: boolean;
+    metadata: boolean;
+    metadataOnly: boolean;
+};
+export type SessionImpactScenario = {
+    name: string;
+    state: 'added' | 'removed' | 'present';
+    impact: ScenarioImpactReason[];
+    baseEffectiveCode: RelationEntry[];
+    headEffectiveCode: RelationEntry[];
+    selectorHits: SessionImpactSelectorHit[];
+    baseScenarioHash: string | null;
+    headScenarioHash: string | null;
+    delta: SessionImpactScenarioDelta;
+};
+export type SessionImpactNodeCause = {
+    kind: 'spec' | 'eval' | 'code' | 'related' | 'contract' | 'measurement';
+    paths: string[];
+    scenarios: string[];
+    selectorHits: SessionImpactSelectorHit[];
+};
+export type SessionImpactNode = {
+    id: string;
+    causes: SessionImpactNodeCause[];
+    scenarios: SessionImpactScenario[];
+};
+export type SessionImpactProjection = {
+    base: string;
+    head: string;
+    revision: string;
+    nodes: SessionImpactNode[];
+};
+export type SessionImpactOptions = {
+    base: string;
+    head: string;
+    measurements?: Readonly<Record<string, readonly string[]>>;
+    overlay?: SessionImpactOverlay;
+};
+export type SessionImpactOverlay = {
+    revision: string;
+    paths: string[];
+    baseRanges: Record<string, [number, number][]>;
+    ranges: Record<string, [number, number][]>;
+    specs: SessionImpactSpecSnapshot[];
+    evalSources: Record<string, string | null>;
+    files: Record<string, string | null>;
+};
+export type SessionImpactSpecSnapshot = Pick<LoadedSpec, 'id' | 'path' | 'code' | 'codeEntries' | 'codeScoped' | 'related' | 'relatedEntries' | 'relatedScoped' | 'relationProblems'>;
+export declare class SessionEvalUnavailableError extends Error {
+    name: string;
+}
+export declare class SessionImpactUnavailableError extends SessionEvalUnavailableError {
+    name: string;
+}
+export declare class SessionImpactRevisionMovedError extends SessionImpactUnavailableError {
+    name: string;
+}
+type LoadedSpec = Awaited<ReturnType<typeof loadSpecs>>[number];
+export declare function projectSessionImpact(root: string, options: SessionImpactOptions): Promise<SessionImpactProjection>;
+export declare function projectSessionImpactUncached(root: string, options: SessionImpactOptions, base: string, head: string): Promise<SessionImpactProjection>;
+type SessionEvalReading = EvalEntry & {
+    inSession: boolean;
+};
+export declare function scopeSessionScenarioRows(current: Scenario[], scenarioInfo: ScenarioInfo[], evals: SessionEvalReading[], projected: readonly SessionImpactScenario[]): {
+    scenarios: SessionScenarioInfo[];
+    evals: SessionEvalReading[];
+};
+export declare function completeExportNodeIds(changedNodeIds: Iterable<string>, scopedNodeIds: Iterable<string>): string[];
+export type ExportReading = {
+    scenario: string;
+    expected: string;
+    impact: ScenarioImpactReason[];
+    verdict?: EvalEntry['verdict'];
+    fresh: boolean;
+    staleAxes: string[];
+    score: ScoreState;
+    evaluator?: string;
+    ts: string;
+    evidence: {
+        kind: 'image';
+        dataUri: string;
+    } | {
+        kind: 'video';
+        dataUri: string;
+    } | {
+        kind: 'transcript';
+        text: string;
+    } | {
+        kind: 'data';
+        text: string;
+    } | {
+        kind: 'miss';
+    } | {
+        kind: 'none';
+    };
+};
+export type ExportUnmeasured = {
+    scenario: string;
+    expected: string;
+    impact: ScenarioImpactReason[];
+};
+export type ExportFile = ReviewDiffFile & {
+    patch: string;
+    oldText: string | null;
+    newText: string | null;
+    truncated: boolean;
+    omitted: boolean;
+};
+export type ExportNode = {
+    id: string;
+    title: string;
+    hue: number;
+    desc: string;
+    files: ExportFile[];
+    additions: number;
+    deletions: number;
+    hasEvalFile: boolean;
+    uncoveredFrontend: boolean;
+    affectedScenarios: number;
+    score: ScoreState;
+    readings: ExportReading[];
+    unmeasured: ExportUnmeasured[];
+};
+export type ExportGate = {
+    label: string;
+    ok: boolean;
+    detail: string;
+};
+export type ExportModel = {
+    id: string;
+    node: string | null;
+    branch: string | null;
+    title: string;
+    generatedAt: string;
+    ahead: number;
+    dirtyNonRuntime: number;
+    gates: ExportGate[];
+    score: {
+        passed: number;
+        total: number;
+        fresh: number;
+    };
+    impact: SessionImpactProjection;
+    nodes: ExportNode[];
+    otherFiles: ExportFile[];
+};
+export declare function buildExportModel(id: string): Promise<ExportModel | null>;
+export declare function scopedScenarioReadings(scenarios: SessionScenarioInfo[], readings: EvalEntry[]): {
+    latest: EvalEntry[];
+    unmeasured: SessionScenarioInfo[];
+};
+export declare function declaredLatest(tl: EvalTimeline): EvalEntry[];
+export declare function nodeScore(hasEvalFile: boolean, latest: EvalEntry[], affectedScenarios?: number): ScoreState;
+export declare function parsePorcelainPaths(out: string): Set<string>;
+export declare function sessionImpactOverlay(wtPath: string, dirty: {
+    paths: ReadonlySet<string>;
+    status: string;
+}): Promise<SessionImpactOverlay | undefined>;
+export declare function renderExportHtml(m: ExportModel): string;
+export type SessionEvalNode = {
+    id: string;
+    title: string;
+    hue: number;
+    desc: string;
+    hasEvalFile: boolean;
+    uncoveredFrontend: boolean;
+    unknownCoverage: string[];
+    causes: SessionImpactNodeCause[];
+    scenarios: SessionScenarioInfo[];
+    evals: (EvalEntry & {
+        inSession: boolean;
+    })[];
+};
+export type SessionEvals = {
+    id: string;
+    node: string | null;
+    branch: string | null;
+    title: string;
+    nodes: SessionEvalNode[];
+    impact: SessionImpactProjection;
+    summary?: SessionEvalSummary;
+    evalRevision: SessionEvalRevision;
+    order?: SessionEvalOrderRow[];
+};
+export type SessionEvalSummary = {
+    measured: number;
+    total: number;
+    pass: number;
+    fail: number;
+    review: number;
+    blind: number;
+    unknown: number;
+};
+export type SessionEvalRevision = {
+    epoch: string;
+    generation: number;
+    content: string;
+};
+export type SessionEvalProjection = {
+    epoch: string;
+    generation: number;
+    phase: 'loading' | 'updating' | 'ready' | 'error';
+    revision?: string;
+    value?: SessionEvalSummary;
+    lastKnown?: {
+        generation: number;
+        revision: string;
+        value: SessionEvalSummary;
+    };
+};
+export declare function sessionEvalSummary(nodes: SessionEvalNode[]): SessionEvalSummary;
+export type SessionEvalOrderRow = {
+    node: string;
+    scenario: string;
+    ts: string | null;
+};
+export type SessionEvalFocus = (order: SessionEvalOrderRow[]) => readonly string[];
+export declare function orderRowsOf(nodes: SessionEvalNode[]): SessionEvalOrderRow[];
+export declare function sessionEvalContentRevision(wtPath: string): Promise<string>;
+type SummaryBuildResult = {
+    kind: 'stable';
+    revision: string;
+    summary: SessionEvalSummary;
+} | {
+    kind: 'unstable';
+} | {
+    kind: 'missing';
+};
+export type SessionEvalSummaryBuilder = (id: string, path: string) => Promise<SummaryBuildResult>;
+type ProjectionTarget = 'all' | {
+    id?: string;
+    path?: string;
+};
+export declare class SessionEvalProjectionCache {
+    private readonly build;
+    readonly epoch: string;
+    private readonly entries;
+    private readonly observerHolds;
+    private readonly observerWaiters;
+    private readonly flights;
+    private notify;
+    private precompute;
+    private readonly demands;
+    constructor(build: SessionEvalSummaryBuilder, notify?: () => void, epoch?: string, precompute?: boolean);
+    setNotify(notify: () => void): void;
+    setPrecompute(enabled: boolean): void;
+    private authorize;
+    private ensureEntry;
+    snapshot(sessions: {
+        id: string;
+        path: string;
+        liveness?: string;
+    }[]): Map<string, SessionEvalProjection>;
+    invalidate(target?: ProjectionTarget): number;
+    holdObserver(observer: string, target?: ProjectionTarget): boolean;
+    releaseObserver(observer: string): boolean;
+    isObserverHeld(id: string, path: string): boolean;
+    waitUntilObservable(id: string, path: string, timeoutMs: number): Promise<boolean>;
+    get(id: string): SessionEvalProjection | null;
+    demand<T>(id: string, path: string, run: () => Promise<T>): Promise<T>;
+    idle(): Promise<void>;
+    accept(id: string, generation: number, revision: string, value: SessionEvalSummary): boolean;
+    private project;
+    private matches;
+    private publish;
+    private startScheduled;
+    private startEntry;
+    private runEntry;
+}
+export declare function setSessionEvalProjectionNotify(notify: () => void): void;
+export declare function setSessionEvalProjectionWarmup(enabled: boolean): void;
+export declare function sessionEvalProjections(sessions: {
+    id: string;
+    path: string;
+    liveness?: string;
+}[]): Map<string, SessionEvalProjection>;
+export declare function sessionEvalProjection(id: string): SessionEvalProjection | null;
+export declare function invalidateSessionEvalProjections(target?: 'all' | {
+    id?: string;
+    path?: string;
+}): number;
+export declare function holdSessionEvalProjectionObserver(observer: string, target?: 'all' | {
+    id?: string;
+    path?: string;
+}): boolean;
+export declare function releaseSessionEvalProjectionObserver(observer: string): boolean;
+export declare function awaitSessionEvalProjectionIdle(): Promise<void>;
+export declare function buildSessionEvals(id: string, pick?: SessionEvalFocus): Promise<SessionEvals | null>;