jev-affected 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export declare class ConfigError extends Error {
+}
+export declare const secretPatterns: string[];
+export declare const configSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    model: z.ZodDefault<z.ZodString>;
+    base: z.ZodOptional<z.ZodString>;
+    policy: z.ZodDefault<z.ZodObject<{
+        uncertain: z.ZodDefault<z.ZodLiteral<"run">>;
+        onError: z.ZodDefault<z.ZodLiteral<"run">>;
+    }, z.core.$strict>>;
+    defaults: z.ZodDefault<z.ZodObject<{
+        skipBelow: z.ZodOptional<z.ZodNumber>;
+        threshold: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    ignore: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    analysis: z.ZodDefault<z.ZodObject<{
+        maxDiffBytes: z.ZodDefault<z.ZodNumber>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    execution: z.ZodDefault<z.ZodObject<{
+        parallel: z.ZodDefault<z.ZodBoolean>;
+        concurrency: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    tasks: z.ZodRecord<z.ZodString, z.ZodObject<{
+        command: z.ZodString;
+        when: z.ZodOptional<z.ZodString>;
+        always: z.ZodDefault<z.ZodBoolean>;
+        allowSkip: z.ZodDefault<z.ZodBoolean>;
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ignore: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        skipBelow: z.ZodOptional<z.ZodNumber>;
+        threshold: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Config = z.infer<typeof configSchema>;
+export declare function parseConfig(value: unknown): Config;
+export declare function loadConfig(path?: string): Promise<Config>;
+export declare const template = "version: 1\nmodel: jev-latest\ndefaults:\n  skipBelow: 0.10\ntasks:\n  unit:\n    command: npm test\n    when: Could this change alter runtime application behavior?\n  typecheck:\n    command: npm run typecheck\n    always: true\n";

package/dist/config.js

@@ -0,0 +1,97 @@
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import { z } from "zod";
+export class ConfigError extends Error {
+}
+const probability = z.number().min(0).max(1);
+const limits = z
+    .object({
+    skipBelow: probability.optional(),
+    threshold: probability.optional(),
+})
+    .strict()
+    .refine((x) => x.skipBelow === undefined || x.threshold === undefined, "Use skipBelow or threshold, not both");
+const patterns = z.array(z.string().min(1));
+export const secretPatterns = [
+    "**/.env*",
+    "**/*.pem",
+    "**/*.key",
+    "**/*credentials*",
+    "**/*secret*",
+    "**/*token*",
+];
+export const configSchema = z
+    .object({
+    version: z.literal(1),
+    model: z.string().min(1).default("jev-latest"),
+    base: z.string().min(1).optional(),
+    policy: z
+        .object({
+        uncertain: z.literal("run").default("run"),
+        onError: z.literal("run").default("run"),
+    })
+        .strict()
+        .default({ uncertain: "run", onError: "run" }),
+    defaults: limits.default({ skipBelow: 0.1 }),
+    ignore: patterns.default([]),
+    analysis: z
+        .object({
+        maxDiffBytes: z.number().int().positive().default(100000),
+        timeoutMs: z.number().int().positive().default(10000),
+        exclude: patterns.default([]),
+    })
+        .strict()
+        .default({ maxDiffBytes: 100000, timeoutMs: 10000, exclude: [] }),
+    execution: z
+        .object({
+        parallel: z.boolean().default(false),
+        concurrency: z.number().int().min(1).max(64).default(4),
+    })
+        .strict()
+        .default({ parallel: false, concurrency: 4 }),
+    tasks: z
+        .record(z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/), z
+        .object({
+        command: z.string().trim().min(1),
+        when: z.string().trim().min(1).optional(),
+        always: z.boolean().default(false),
+        allowSkip: z.boolean().default(true),
+        include: patterns.optional(),
+        ignore: patterns.default([]),
+        skipBelow: probability.optional(),
+        threshold: probability.optional(),
+    })
+        .strict()
+        .refine((t) => t.always || !t.allowSkip || !!t.when, "when is required for skippable tasks")
+        .refine((t) => t.skipBelow === undefined || t.threshold === undefined, "Use skipBelow or threshold, not both"))
+        .refine((t) => Object.keys(t).length > 0, "At least one task is required"),
+})
+    .strict();
+export function parseConfig(value) {
+    const r = configSchema.safeParse(value);
+    if (!r.success)
+        throw new ConfigError(r.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("\n"));
+    return r.data;
+}
+export async function loadConfig(path = "jev-affected.yml") {
+    try {
+        return parseConfig(parse(await readFile(path, "utf8")));
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            throw e;
+        throw new ConfigError("Cannot read or parse YAML configuration.");
+    }
+}
+export const template = `version: 1
+model: jev-latest
+defaults:
+  skipBelow: 0.10
+tasks:
+  unit:
+    command: npm test
+    when: Could this change alter runtime application behavior?
+  typecheck:
+    command: npm run typecheck
+    always: true
+`;

package/dist/eval.d.ts

@@ -0,0 +1,41 @@
+export declare function evaluate(directory: string, live?: boolean): Promise<{
+    mode: string;
+    cases: {
+        name: any;
+        falseSkips: number;
+        model: string | null;
+        usage: {
+            input_tokens: number;
+            output_tokens: number;
+        } | undefined;
+        selected: number;
+        tasks: {
+            id: string;
+            expected: any;
+            decision: "run" | "skip";
+            probability: number | null;
+            threshold: number;
+            reason: string;
+        }[];
+    }[];
+    falseSkips: number;
+    invalidCases: number;
+    reducedCases: number;
+    passed: boolean;
+    falseSkipRate: number;
+    unnecessaryRunRate: number;
+    taskReduction: number;
+    apiCalls: number;
+    latencyMs: number;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    gate: {
+        maxFalseSkips: number;
+        maxInvalidCases: number;
+        minReducedCases: number;
+        minTaskReduction: number;
+    };
+    analysisCost: null;
+}>;

package/dist/eval.js

@@ -0,0 +1,96 @@
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { ConfigError, parseConfig } from "./config.js";
+import { createPlan } from "./planner.js";
+import { JevProvider } from "./provider.js";
+export async function evaluate(directory, live = false) {
+    let required = 0, unneeded = 0, falseSkips = 0, unnecessaryRuns = 0, skipped = 0, total = 0, apiCalls = 0, latencyMs = 0, invalidCases = 0, reducedCases = 0, inputTokens = 0, outputTokens = 0;
+    const cases = [];
+    for (const file of (await readdir(directory))
+        .filter((f) => f.endsWith(".json"))
+        .sort()) {
+        const fixture = JSON.parse(await readFile(resolve(directory, file), "utf8"));
+        const config = parseConfig(fixture.config);
+        if (!fixture.expected ||
+            Object.keys(fixture.expected).length !== Object.keys(config.tasks).length)
+            throw new ConfigError("Each evaluation task needs an expected decision.");
+        const plan = await createPlan({
+            config,
+            state: fixture.state,
+            cache: false,
+            provider: live
+                ? new JevProvider()
+                : { analyze: async () => fixture.response },
+        });
+        let misses = 0;
+        for (const t of plan.tasks) {
+            const expected = fixture.expected[t.id];
+            if (expected !== "run" && expected !== "skip")
+                throw new ConfigError("Invalid evaluation expectation");
+            total++;
+            if (t.decision === "skip")
+                skipped++;
+            if (expected === "run") {
+                required++;
+                if (t.decision === "skip") {
+                    falseSkips++;
+                    misses++;
+                }
+            }
+            else {
+                unneeded++;
+                if (t.decision === "run")
+                    unnecessaryRuns++;
+            }
+        }
+        apiCalls += live ? plan.metrics.apiCalls : 0;
+        inputTokens += plan.metrics.usage?.input_tokens ?? 0;
+        outputTokens += plan.metrics.usage?.output_tokens ?? 0;
+        if (plan.tasks.some((t) => ["provider-fallback", "invalid-answer", "incomplete-state"].includes(t.reason)))
+            invalidCases++;
+        if (plan.tasks.some((t) => t.decision === "skip"))
+            reducedCases++;
+        latencyMs += plan.metrics.latencyMs;
+        cases.push({
+            name: fixture.name,
+            falseSkips: misses,
+            model: plan.model,
+            usage: plan.metrics.usage,
+            selected: plan.tasks.filter((t) => t.decision === "run").length,
+            tasks: plan.tasks.map((t) => ({
+                id: t.id,
+                expected: fixture.expected[t.id],
+                decision: t.decision,
+                probability: t.probability,
+                threshold: t.threshold,
+                reason: t.reason,
+            })),
+        });
+    }
+    if (!cases.length)
+        throw new ConfigError("No evaluation fixtures found.");
+    return {
+        mode: live ? "live" : "synthetic-offline",
+        cases,
+        falseSkips,
+        invalidCases,
+        reducedCases,
+        passed: falseSkips === 0 &&
+            invalidCases === 0 &&
+            reducedCases >= 2 &&
+            (total ? skipped / total : 0) >= 0.25,
+        falseSkipRate: required ? falseSkips / required : 0,
+        unnecessaryRunRate: unneeded ? unnecessaryRuns / unneeded : 0,
+        taskReduction: total ? skipped / total : 0,
+        apiCalls,
+        latencyMs,
+        usage: { inputTokens, outputTokens },
+        gate: {
+            maxFalseSkips: 0,
+            maxInvalidCases: 0,
+            minReducedCases: 2,
+            minTaskReduction: 0.25,
+        },
+        analysisCost: null,
+    };
+}

package/dist/executor.d.ts

@@ -0,0 +1,6 @@
+import type { Plan } from "./planner.js";
+export declare function executePlan(plan: Plan, options?: {
+    cwd?: string;
+    concurrency?: number;
+    json?: boolean;
+}): Promise<number>;

package/dist/executor.js

@@ -0,0 +1,68 @@
+import { spawn } from "node:child_process";
+export async function executePlan(plan, options = {}) {
+    const tasks = plan.tasks.filter((t) => t.decision === "run");
+    const concurrency = options.concurrency ?? 1;
+    if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 64)
+        throw new RangeError("concurrency must be an integer from 1 to 64");
+    const children = new Set();
+    let interrupted = false;
+    const stop = () => {
+        interrupted = true;
+        for (const child of children) {
+            if (!child.pid)
+                continue;
+            if (process.platform === "win32") {
+                const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], { stdio: "ignore", windowsHide: true });
+                killer.on("error", () => child.kill());
+            }
+            else {
+                try {
+                    process.kill(-child.pid, "SIGTERM");
+                }
+                catch {
+                    child.kill();
+                }
+            }
+        }
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    let next = 0, failed = false;
+    const worker = async () => {
+        while (!interrupted && next < tasks.length) {
+            const task = tasks[next++];
+            if (!task)
+                break;
+            const code = await new Promise((resolve) => {
+                const child = spawn(task.command, {
+                    cwd: options.cwd,
+                    shell: true,
+                    detached: process.platform !== "win32",
+                    windowsHide: true,
+                    stdio: options.json
+                        ? ["inherit", process.stderr, process.stderr]
+                        : "inherit",
+                });
+                children.add(child);
+                child.on("error", () => {
+                    children.delete(child);
+                    resolve(1);
+                });
+                child.on("close", (code) => {
+                    children.delete(child);
+                    resolve(code ?? 1);
+                });
+            });
+            if (code !== 0)
+                failed = true;
+        }
+    };
+    try {
+        await Promise.all(Array.from({ length: Math.min(tasks.length, concurrency) }, worker));
+    }
+    finally {
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+    }
+    return failed || interrupted ? 1 : 0;
+}

package/dist/git.d.ts

@@ -0,0 +1,21 @@
+import { type Config } from "./config.js";
+export declare function git(cwd: string, ...args: string[]): Promise<string>;
+export declare const matches: (path: string, patterns: string[]) => boolean;
+export interface ChangedFile {
+    path: string;
+    oldPath?: string;
+    status: string;
+}
+export interface ChangeState {
+    base: string;
+    head: string;
+    files: ChangedFile[];
+    diff: string;
+    incomplete: boolean;
+    warnings: string[];
+}
+export declare function collectChanges(config: Config, options?: {
+    cwd?: string;
+    base?: string;
+    head?: string;
+}): Promise<ChangeState>;

package/dist/git.js

@@ -0,0 +1,102 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import picomatch from "picomatch";
+import { ConfigError, secretPatterns } from "./config.js";
+const exec = promisify(execFile);
+export async function git(cwd, ...args) {
+    return (await exec("git", args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 32 * 1024 * 1024,
+        env: { ...process.env, GIT_LITERAL_PATHSPECS: "1" },
+    })).stdout;
+}
+export const matches = (path, patterns) => patterns.length > 0 && picomatch(patterns, { dot: true })(path);
+export async function collectChanges(config, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const resolve = async (ref) => (await git(cwd, "rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`)).trim();
+    let head;
+    try {
+        head = await resolve(options.head ?? "HEAD");
+    }
+    catch {
+        throw new ConfigError("Cannot resolve head commit.");
+    }
+    const explicit = options.base ?? config.base;
+    const candidates = explicit
+        ? [explicit]
+        : [
+            process.env.GITHUB_BASE_REF
+                ? `origin/${process.env.GITHUB_BASE_REF}`
+                : undefined,
+            "origin/main",
+            "main",
+            "master",
+        ].filter((x) => !!x);
+    let base;
+    for (const ref of candidates) {
+        try {
+            base = (await git(cwd, "merge-base", await resolve(ref), head)).trim();
+            break;
+        }
+        catch { }
+    }
+    if (!base)
+        throw new ConfigError("Cannot resolve Git base. Fetch the base branch or pass --base.");
+    const parts = (await git(cwd, "diff", "--name-status", "-z", "--find-renames", base, head, "--")).split("\0");
+    const files = [];
+    for (let i = 0; i < parts.length && parts[i];) {
+        const status = parts[i++];
+        const path = parts[i++];
+        if (!status || !path)
+            throw new Error("Malformed Git file listing");
+        if (status.startsWith("R") || status.startsWith("C")) {
+            const target = parts[i++];
+            if (!target)
+                throw new Error("Malformed Git rename listing");
+            files.push({ status, oldPath: path, path: target });
+        }
+        else
+            files.push({ status, path });
+    }
+    const state = {
+        base,
+        head,
+        files: [],
+        diff: "",
+        incomplete: false,
+        warnings: [],
+    };
+    for (const file of files) {
+        const paths = [file.path, ...(file.oldPath ? [file.oldPath] : [])];
+        if (paths.some((p) => matches(p, [...secretPatterns, ...config.analysis.exclude]))) {
+            state.incomplete = true;
+            state.warnings.push("Excluded sensitive file change; running all tasks.");
+            continue;
+        }
+        if (paths.every((p) => matches(p, config.ignore)))
+            continue;
+        state.files.push(file);
+        try {
+            const patch = await git(cwd, "diff", "--no-ext-diff", "--no-textconv", "--find-renames", "--unified=3", base, head, "--", ...paths);
+            if (patch.includes("Binary files ") ||
+                patch.includes("Subproject commit ")) {
+                state.incomplete = true;
+                state.warnings.push("Binary or submodule change; running all tasks.");
+            }
+            if (Buffer.byteLength(state.diff) + Buffer.byteLength(patch) >
+                config.analysis.maxDiffBytes) {
+                state.incomplete = true;
+                state.warnings.push("Diff exceeds analysis limit; running all tasks.");
+            }
+            else
+                state.diff += patch;
+        }
+        catch {
+            state.incomplete = true;
+            state.warnings.push("Diff could not be read; running all tasks.");
+        }
+    }
+    state.warnings = [...new Set(state.warnings)];
+    return state;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type Config, ConfigError, loadConfig, parseConfig } from "./config.js";
+export { executePlan } from "./executor.js";
+export { type ChangeState, collectChanges } from "./git.js";
+export { createPlan, type Plan, type TaskDecision } from "./planner.js";
+export { type AnalysisInput, type AnalysisResult, type DecisionProvider, JevProvider, } from "./provider.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { ConfigError, loadConfig, parseConfig } from "./config.js";
+export { executePlan } from "./executor.js";
+export { collectChanges } from "./git.js";
+export { createPlan } from "./planner.js";
+export { JevProvider, } from "./provider.js";

package/dist/planner.d.ts

@@ -0,0 +1,37 @@
+import { type Config } from "./config.js";
+import { type ChangeState } from "./git.js";
+import { type AnalysisResult, type DecisionProvider } from "./provider.js";
+export interface TaskDecision {
+    id: string;
+    command: string;
+    condition?: string;
+    decision: "run" | "skip";
+    probability: number | null;
+    threshold: number;
+    reason: string;
+    files: string[];
+}
+export interface Plan {
+    version: 1;
+    base: string;
+    head: string;
+    model: string | null;
+    requestedModel: string;
+    tasks: TaskDecision[];
+    warnings: string[];
+    metrics: {
+        apiCalls: number;
+        cacheHits: number;
+        latencyMs: number;
+        usage?: AnalysisResult["usage"];
+    };
+}
+export declare function createPlan(input: {
+    config: Config;
+    cwd?: string;
+    base?: string;
+    head?: string;
+    state?: ChangeState;
+    provider?: DecisionProvider;
+    cache?: boolean;
+}): Promise<Plan>;

package/dist/planner.js

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseConfig, secretPatterns } from "./config.js";
+import { collectChanges, git, matches } from "./git.js";
+import { JevProvider, } from "./provider.js";
+export async function createPlan(input) {
+    const start = Date.now(), config = parseConfig(input.config), cwd = input.cwd ?? process.cwd();
+    const state = structuredClone(input.state ?? (await collectChanges(config, input)));
+    if (Buffer.byteLength(state.diff) > config.analysis.maxDiffBytes ||
+        state.files.some((f) => [f.path, ...(f.oldPath ? [f.oldPath] : [])].some((p) => matches(p, [...secretPatterns, ...config.analysis.exclude])))) {
+        state.incomplete = true;
+        state.diff = "";
+        state.warnings.push("Supplied state exceeds analysis limits or includes excluded paths; running all tasks.");
+    }
+    const plan = {
+        version: 1,
+        base: state.base,
+        head: state.head,
+        model: null,
+        requestedModel: config.model,
+        tasks: [],
+        warnings: [...state.warnings],
+        metrics: { apiCalls: 0, cacheHits: 0, latencyMs: 0 },
+    };
+    const questions = Object.create(null);
+    for (const [id, t] of Object.entries(config.tasks)) {
+        const files = state.files
+            .filter((f) => [f.path, ...(f.oldPath ? [f.oldPath] : [])].some((p) => (!t.include || matches(p, t.include)) && !matches(p, t.ignore)))
+            .map((f) => f.path);
+        const task = {
+            id,
+            command: t.command,
+            condition: t.when,
+            decision: "run",
+            probability: null,
+            threshold: t.skipBelow ??
+                t.threshold ??
+                config.defaults.skipBelow ??
+                config.defaults.threshold ??
+                0.1,
+            reason: "semantic",
+            files,
+        };
+        if (t.always || !t.allowSkip)
+            task.reason = "protected";
+        else if (state.incomplete)
+            task.reason = "incomplete-state";
+        else if (!files.length) {
+            task.decision = "skip";
+            task.reason = "no-matching-changes";
+        }
+        else if (t.when)
+            questions[id] = t.when;
+        plan.tasks.push(task);
+    }
+    if (Object.keys(questions).length) {
+        let result;
+        let cachePath;
+        const pinned = /^jev-\d+\.\d+\.\d+$/.test(config.model);
+        if (input.cache !== false && !input.provider && pinned) {
+            try {
+                const dir = resolve(cwd, (await git(cwd, "rev-parse", "--git-path", "jev-affected/cache")).trim());
+                const key = createHash("sha256")
+                    .update(JSON.stringify({
+                    version: 1,
+                    model: config.model,
+                    config,
+                    questions,
+                    state,
+                }))
+                    .digest("hex");
+                cachePath = resolve(dir, `${key}.json`);
+                const cached = JSON.parse(await readFile(cachePath, "utf8"));
+                if (cached.model === config.model) {
+                    result = cached;
+                    plan.metrics.cacheHits = 1;
+                }
+            }
+            catch { }
+        }
+        try {
+            if (!result) {
+                plan.metrics.apiCalls = 1;
+                result = await (input.provider ?? new JevProvider()).analyze({
+                    state,
+                    questions,
+                    model: config.model,
+                    timeoutMs: config.analysis.timeoutMs,
+                });
+            }
+            if (!result.model || !/^jev-\d+\.\d+\.\d+$/.test(result.model))
+                throw new Error("Missing actual model version");
+            plan.model = result.model;
+            plan.metrics.usage = result.usage;
+            for (const task of plan.tasks) {
+                if (!(task.id in questions))
+                    continue;
+                const p = result.probabilities[task.id];
+                if (typeof p !== "number" || !Number.isFinite(p) || p < 0 || p > 1) {
+                    task.reason = "invalid-answer";
+                    continue;
+                }
+                task.probability = p;
+                task.decision = p < task.threshold ? "skip" : "run";
+            }
+            if (cachePath &&
+                result.model === config.model &&
+                plan.tasks.every((t) => t.reason !== "invalid-answer")) {
+                try {
+                    await mkdir(resolve(cachePath, ".."), { recursive: true });
+                    await writeFile(cachePath, JSON.stringify(result), { mode: 0o600 });
+                }
+                catch {
+                    plan.warnings.push("Cache could not be written.");
+                }
+            }
+        }
+        catch {
+            for (const t of plan.tasks) {
+                if (t.id in questions) {
+                    t.decision = "run";
+                    t.probability = null;
+                    t.reason = "provider-fallback";
+                }
+            }
+            plan.warnings.push("Jev unavailable or response invalid; running candidate tasks.");
+        }
+    }
+    plan.metrics.latencyMs = Date.now() - start;
+    return plan;
+}

package/dist/provider.d.ts

@@ -0,0 +1,21 @@
+import type { ChangeState } from "./git.js";
+export interface AnalysisInput {
+    state: ChangeState;
+    questions: Record<string, string>;
+    model: string;
+    timeoutMs: number;
+}
+export interface AnalysisResult {
+    model: string;
+    probabilities: Record<string, number>;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+export interface DecisionProvider {
+    analyze(input: AnalysisInput): Promise<AnalysisResult>;
+}
+export declare class JevProvider implements DecisionProvider {
+    analyze(input: AnalysisInput): Promise<AnalysisResult>;
+}