jev-affected 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0
+
+- Add a repository-owned `jev-affected.yml` for dogfooding this project.
+- Analyze committed, working-tree, or staged changes with explicit input modes.
+- Detect pull-request base branches across GitHub Actions, GitLab CI, Buildkite,
+  and mapped CircleCI pipeline values.
+- Inspect and safely clear the Git-local semantic decision cache.
+- Avoid treating source text that mentions Git submodule markers as an actual
+  submodule diff.
+
 ## 0.2.0
 
 - Read API credentials from the process environment only.

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center"><strong>Semantic task routing for software development.</strong></p>
 <p align="center">Run tasks based on what changed, not where it changed.</p>
-<p align="center">v0.2.0 Public Beta · Node.js 20+ · TypeScript · MIT · Jev-powered</p>
+<p align="center">v0.3.0 Public Beta · Node.js 20+ · TypeScript · MIT · Jev-powered</p>
 
 ![Illustrative offline fixture demo, not live Jev output](assets/demo.gif)
 
@@ -50,7 +50,14 @@ npx jev-affected plan --base main
 npx jev-affected run --base main
 ```
 
-`plan` performs analysis but never executes task commands. `run` executes configured commands. **Only committed changes are included**: default head is `HEAD`, not the working tree. Commit agent edits before planning.
+`plan` performs analysis but never executes task commands. `run` executes configured commands. The default mode compares committed changes. Use `--working-tree` to include branch commits, staged changes, unstaged changes and untracked files, or `--staged` to analyze only the Git index.
+
+```sh
+npx jev-affected plan --working-tree --base main
+npx jev-affected plan --staged
+```
+
+`--working-tree` accepts `--base` but not `--head`. `--staged` compares the index with `HEAD` and cannot be combined with `--base` or `--head`.
 
 ## How it works
 
@@ -121,12 +128,13 @@ Low model probabilities are estimates, not a guarantee that a task is unnecessar
 | `inspect` | Preview sanitized analysis inputs locally; no request |
 | `doctor` | Check Node, config, Git base, API key and models endpoint |
 | `eval [--live]` | Evaluate fixture decisions and false-skip rate |
+| `cache [status\|clear]` | Inspect or remove the Git-local decision cache |
 
-Common flags: `--base`, `--head`, `--config`, `--no-cache`, `--json`, `--help`, `--version`. JSON task output includes a stable `version: 1`. During `run --json`, child output goes to stderr, keeping stdout parseable.
+Common flags: `--base`, `--head`, `--working-tree`, `--staged`, `--config`, `--no-cache`, `--json`, `--help`, `--version`. JSON task output includes a stable `version: 1`. During `run --json`, child output goes to stderr, keeping stdout parseable.
 
 Exit codes: `0` success; `1` failed executed task or failed evaluation gate; `2` config/argument/base or doctor check error; `3` internal/I/O failure. API failures do not fail a normal plan or run by themselves.
 
-Base priority: CLI → config → GitHub PR base branch → `origin/main` → `main` → `master`. The comparison starts at the merge-base with head. Explicit invalid bases fail instead of silently choosing another branch. Fetch full history in CI.
+Base priority: CLI → config → detected CI target → `origin/HEAD` → `origin/main` → `main` → `master`. The comparison starts at the merge-base with head. Explicit invalid bases fail instead of silently choosing another branch. Fetch full history in CI.
 
 ## CI
 
@@ -141,9 +149,18 @@ Base priority: CLI → config → GitHub PR base branch → `origin/main` → `m
 
 Install dependencies first. Do not expose credentials to untrusted PR code. Nx, Turbo and other runners can be invoked as configured commands; no plugins are required.
 
+Target branches are detected from GitHub Actions, GitLab CI and Buildkite variables. CircleCI exposes the PR base as a pipeline value rather than a legacy job environment variable; map it to `CIRCLE_PR_BASE_BRANCH` in the job when using automatic detection. `--base` and `base` in configuration remain the explicit overrides.
+
+| CI | Base input |
+| --- | --- |
+| GitHub Actions | `GITHUB_BASE_REF` |
+| GitLab CI | merge-request diff base SHA, target branch, then default branch |
+| Buildkite | `BUILDKITE_PULL_REQUEST_BASE_BRANCH` |
+| CircleCI | `CIRCLE_PR_BASE_BRANCH` supplied from the PR base pipeline value |
+
 ## Agents
 
-After committing edits, run `jev-affected plan --json` and execute all tasks whose `decision` is `run`, or use `jev-affected run`. `inspect` lets you review what could leave the repository first.
+Run `jev-affected plan --json --working-tree` while editing, or use the default committed mode after committing. Execute all tasks whose `decision` is `run`, or use `jev-affected run` with the same mode. `inspect` lets you review what could leave the repository first.
 
 The package includes a reusable agent skill at [`skills/jev-affected`](skills/jev-affected). Point a compatible coding agent at that directory, or copy it into the agent's skills directory, to give it the safe planning and execution workflow.
 
@@ -159,6 +176,8 @@ const plan = await createPlan({ config, base: 'main' });
 
 Automatic caches store probabilities and model metadata in `.git/jev-affected/cache` (including Git worktree support). Keys include state, questions, configuration and pinned actual model version. Corrupt cache entries fall back to RUN. **Moving aliases such as `jev-latest` bypass caching**, because an alias cannot safely establish its current actual version without another request. Pin an actual `jev-x.y.z` version to enable reuse. Neither patches nor API keys are stored in cache payloads. Cache writes are the only local side effect of `plan`; `--no-cache` disables them.
 
+Use `jev-affected cache status` to inspect entry count and size, and `jev-affected cache clear` to remove only the cache directory resolved inside Git metadata. Both commands support `--json` and do not require a project configuration file.
+
 ## Evaluation
 
 ```sh
@@ -184,11 +203,11 @@ No backend and no telemetry. Data is read locally; semantic inputs go directly t
 
 **What if Jev is down?** Candidate tasks run. Deterministic rules and protected tasks still apply.
 
-**Are uncommitted files included?** No, v0.1 compares commits. Explicit refs make the input reproducible.
+**Are uncommitted files included?** Only with `--working-tree` or `--staged`. Default mode compares commits so explicit refs remain reproducible.
 
 ## Roadmap
 
-v0.1 focuses on inspectable semantic dependencies and safe task plans. Later candidates: working-tree mode, historical evaluations, watch mode, task groups and Nx/Turbo adapters. No GUI, SaaS, MCP server or autonomous command generation is included.
+The current release focuses on inspectable semantic dependencies and safe plans for committed, working-tree and staged changes. Later candidates include historical evaluations, watch mode, task groups and Nx/Turbo adapters. No GUI, SaaS, MCP server or autonomous command generation is included.
 
 ## Contributing and license
 

package/dist/cache.d.ts

@@ -0,0 +1,8 @@
+export interface CacheInfo {
+    path: string;
+    entries: number;
+    bytes: number;
+}
+export declare function cacheDirectory(cwd?: string): Promise<string>;
+export declare function inspectCache(cwd?: string): Promise<CacheInfo>;
+export declare function clearCache(cwd?: string): Promise<CacheInfo>;

package/dist/cache.js

@@ -0,0 +1,35 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { ConfigError } from "./config.js";
+import { git } from "./git.js";
+export async function cacheDirectory(cwd = process.cwd()) {
+    const common = resolve(cwd, (await git(cwd, "rev-parse", "--git-common-dir")).trim());
+    const directory = resolve(cwd, (await git(cwd, "rev-parse", "--git-path", "jev-affected/cache")).trim());
+    const fromCommon = relative(common, directory);
+    if (!fromCommon || fromCommon.startsWith("..") || isAbsolute(fromCommon))
+        throw new ConfigError("Cannot resolve a safe Git cache directory.");
+    return directory;
+}
+export async function inspectCache(cwd = process.cwd()) {
+    const path = await cacheDirectory(cwd);
+    let names;
+    try {
+        names = (await readdir(path)).filter((name) => name.endsWith(".json"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { path, entries: 0, bytes: 0 };
+        throw error;
+    }
+    const sizes = await Promise.all(names.map(async (name) => (await stat(resolve(path, name))).size));
+    return {
+        path,
+        entries: names.length,
+        bytes: sizes.reduce((total, size) => total + size, 0),
+    };
+}
+export async function clearCache(cwd = process.cwd()) {
+    const info = await inspectCache(cwd);
+    await rm(info.path, { recursive: true, force: true });
+    return info;
+}

package/dist/cli.js

@@ -4,6 +4,7 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { TypeSafeClient } from "@typesafe-ai/sdk";
+import { clearCache, inspectCache } from "./cache.js";
 import { ConfigError, loadConfig, resolveApiKey, template } from "./config.js";
 import { evaluate } from "./eval.js";
 import { executePlan } from "./executor.js";
@@ -34,6 +35,8 @@ async function main() {
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
                 "no-cache": { type: "boolean" },
+                "working-tree": { type: "boolean" },
+                staged: { type: "boolean" },
                 fixtures: { type: "string" },
                 live: { type: "boolean" },
             },
@@ -52,13 +55,15 @@ async function main() {
         console.log(`jev-affected — Semantic task routing, powered by Jev.
 
 Usage: jev-affected <command> [options]
-Commands: init, plan, run, why <task>, inspect, doctor, eval
+Commands: init, plan, run, why <task>, inspect, doctor, eval, cache [status|clear]
 Options:
   --base <ref>       Compare from merge-base(ref, head)
   --head <ref>       Head commit (default HEAD; committed changes only)
   --config <file>    YAML configuration
   --json            Machine-readable output
   --no-cache        Bypass the local decision cache
+  --working-tree    Include committed, staged, unstaged and untracked changes
+  --staged          Analyze only changes staged against HEAD
   --parallel        Execute selected commands concurrently
   --concurrency <n>  Maximum parallel commands
   --fixtures <dir>  Evaluation fixtures (default evals/fixtures)
@@ -68,11 +73,39 @@ Options:
 inspect never sends requests. plan never executes task commands.`);
         return;
     }
-    if (!["init", "plan", "run", "why", "inspect", "doctor", "eval"].includes(command))
+    if (![
+        "init",
+        "plan",
+        "run",
+        "why",
+        "inspect",
+        "doctor",
+        "eval",
+        "cache",
+    ].includes(command))
         throw new ConfigError("Unknown command. See --help.");
-    if (positionals.length > (command === "why" ? 2 : 1))
+    if (positionals.length > (["why", "cache"].includes(command) ? 2 : 1))
         throw new ConfigError("Unexpected positional arguments.");
+    if (v["working-tree"] && v.staged)
+        throw new ConfigError("Use --working-tree or --staged, not both.");
+    if (v["working-tree"] && v.head)
+        throw new ConfigError("--working-tree cannot be combined with --head.");
+    if (v.staged && (v.base || v.head))
+        throw new ConfigError("--staged cannot be combined with --base or --head.");
     const emit = (x) => console.log(JSON.stringify(x, null, 2));
+    if (command === "cache") {
+        const action = positionals[1] ?? "status";
+        if (!["status", "clear"].includes(action))
+            throw new ConfigError("Use cache status or cache clear.");
+        const info = action === "clear" ? await clearCache() : await inspectCache();
+        if (v.json)
+            emit({ action, ...info });
+        else if (action === "clear")
+            console.log(`Cleared ${info.entries} cache entries (${info.bytes} bytes).`);
+        else
+            console.log(`Cache: ${info.entries} entries, ${info.bytes} bytes\n${info.path}`);
+        return;
+    }
     if (command === "init") {
         try {
             await writeFile(String(v.config ?? "jev-affected.yml"), template, {
@@ -103,6 +136,8 @@ inspect never sends requests. plan never executes task commands.`);
         base: typeof v.base === "string" ? v.base : undefined,
         head: typeof v.head === "string" ? v.head : undefined,
         cache: !v["no-cache"],
+        workingTree: !!v["working-tree"],
+        staged: !!v.staged,
     };
     if (command === "why" &&
         (!positionals[1] || !Object.hasOwn(config.tasks, positionals[1])))

package/dist/git.d.ts

@@ -14,8 +14,12 @@ export interface ChangeState {
     incomplete: boolean;
     warnings: string[];
 }
-export declare function collectChanges(config: Config, options?: {
+export interface ChangeOptions {
     cwd?: string;
     base?: string;
     head?: string;
-}): Promise<ChangeState>;
+    workingTree?: boolean;
+    staged?: boolean;
+}
+export declare function detectCiBaseCandidates(env?: NodeJS.ProcessEnv): string[];
+export declare function collectChanges(config: Config, options?: ChangeOptions): Promise<ChangeState>;

package/dist/git.js

@@ -1,4 +1,6 @@
 import { execFile } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
 import { promisify } from "node:util";
 import picomatch from "picomatch";
 import { ConfigError, secretPatterns } from "./config.js";
@@ -12,38 +14,88 @@ export async function git(cwd, ...args) {
     })).stdout;
 }
 export const matches = (path, patterns) => patterns.length > 0 && picomatch(patterns, { dot: true })(path);
+const branchRefs = (value) => {
+    const branch = value?.trim().replace(/^refs\/heads\//, "");
+    if (!branch || branch === "false")
+        return [];
+    if (branch.startsWith("origin/") || /^[0-9a-f]{7,40}$/.test(branch))
+        return [branch];
+    return [`origin/${branch}`, branch];
+};
+export function detectCiBaseCandidates(env = process.env) {
+    const refs = [
+        ...branchRefs(env.GITHUB_BASE_REF),
+        ...(env.GITLAB_CI === "true"
+            ? [
+                ...branchRefs(env.CI_MERGE_REQUEST_DIFF_BASE_SHA),
+                ...branchRefs(env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME),
+                ...branchRefs(env.CI_DEFAULT_BRANCH),
+            ]
+            : []),
+        ...(env.BUILDKITE === "true"
+            ? branchRefs(env.BUILDKITE_PULL_REQUEST_BASE_BRANCH)
+            : []),
+        ...(env.CIRCLECI === "true" ? branchRefs(env.CIRCLE_PR_BASE_BRANCH) : []),
+    ];
+    return [...new Set(refs)];
+}
+const hasUnsupportedPatch = (patch) => /^Binary files .+ differ$/m.test(patch) ||
+    /^[+-]Subproject commit [0-9a-f]{7,}(?:-dirty)?$/m.test(patch);
+async function untrackedPatch(cwd, path) {
+    try {
+        return await git(cwd, "diff", "--no-index", "--no-ext-diff", "--no-textconv", "--unified=3", "--", "/dev/null", path);
+    }
+    catch (error) {
+        const result = error;
+        if (Number(result.code) === 1 && typeof result.stdout === "string")
+            return result.stdout;
+        throw error;
+    }
+}
 export async function collectChanges(config, options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    if (options.workingTree && options.staged)
+        throw new ConfigError("Use --working-tree or --staged, not both.");
+    if (options.workingTree && options.head)
+        throw new ConfigError("--working-tree cannot be combined with --head.");
+    if (options.staged && (options.base || options.head))
+        throw new ConfigError("--staged cannot be combined with --base or --head.");
     const resolve = async (ref) => (await git(cwd, "rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`)).trim();
-    let head;
+    let headCommit;
     try {
-        head = await resolve(options.head ?? "HEAD");
+        headCommit = await resolve(options.head ?? "HEAD");
     }
     catch {
         throw new ConfigError("Cannot resolve head commit.");
     }
-    const explicit = options.base ?? config.base;
+    const explicit = options.staged ? "HEAD" : (options.base ?? config.base);
     const candidates = explicit
         ? [explicit]
         : [
-            process.env.GITHUB_BASE_REF
-                ? `origin/${process.env.GITHUB_BASE_REF}`
-                : undefined,
+            ...detectCiBaseCandidates(),
+            "origin/HEAD",
             "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();
+            base = options.staged
+                ? await resolve("HEAD")
+                : (await git(cwd, "merge-base", await resolve(ref), headCommit)).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 comparison = options.staged
+        ? ["--cached", base]
+        : options.workingTree
+            ? [base]
+            : [base, headCommit];
+    const parts = (await git(cwd, "diff", "--name-status", "-z", "--find-renames", ...comparison, "--")).split("\0");
     const files = [];
     for (let i = 0; i < parts.length && parts[i];) {
         const status = parts[i++];
@@ -59,9 +111,23 @@ export async function collectChanges(config, options = {}) {
         else
             files.push({ status, path });
     }
+    if (options.workingTree) {
+        const tracked = new Set(files.flatMap((file) => [
+            file.path,
+            ...(file.oldPath ? [file.oldPath] : []),
+        ]));
+        for (const path of (await git(cwd, "ls-files", "--others", "--exclude-standard", "-z", "--")).split("\0")) {
+            if (path && !tracked.has(path))
+                files.push({ status: "A", path });
+        }
+    }
     const state = {
         base,
-        head,
+        head: options.staged
+            ? "INDEX"
+            : options.workingTree
+                ? "WORKTREE"
+                : headCommit,
         files: [],
         diff: "",
         incomplete: false,
@@ -78,9 +144,19 @@ export async function collectChanges(config, options = {}) {
             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 ")) {
+            if (options.workingTree && file.status === "A") {
+                const size = (await stat(resolvePath(cwd, file.path))).size;
+                if (Buffer.byteLength(state.diff) + size >
+                    config.analysis.maxDiffBytes) {
+                    state.incomplete = true;
+                    state.warnings.push("Diff exceeds analysis limit; running all tasks.");
+                    continue;
+                }
+            }
+            const patch = options.workingTree && file.status === "A"
+                ? await untrackedPatch(cwd, file.path)
+                : await git(cwd, "diff", "--no-ext-diff", "--no-textconv", "--find-renames", "--unified=3", ...(options.staged ? ["--cached", base] : comparison), "--", ...paths);
+            if (hasUnsupportedPatch(patch)) {
                 state.incomplete = true;
                 state.warnings.push("Binary or submodule change; running all tasks.");
             }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+export { type CacheInfo, cacheDirectory, clearCache, inspectCache, } from "./cache.js";
 export { API_KEY_VARS, type Config, ConfigError, loadConfig, parseConfig, resolveApiKey, } from "./config.js";
 export { executePlan } from "./executor.js";
-export { type ChangeState, collectChanges } from "./git.js";
+export { type ChangedFile, type ChangeOptions, type ChangeState, collectChanges, detectCiBaseCandidates, } 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

@@ -1,5 +1,6 @@
+export { cacheDirectory, clearCache, inspectCache, } from "./cache.js";
 export { API_KEY_VARS, ConfigError, loadConfig, parseConfig, resolveApiKey, } from "./config.js";
 export { executePlan } from "./executor.js";
-export { collectChanges } from "./git.js";
+export { collectChanges, detectCiBaseCandidates, } from "./git.js";
 export { createPlan } from "./planner.js";
 export { JevProvider, } from "./provider.js";

package/dist/planner.d.ts

@@ -1,5 +1,5 @@
 import { type Config } from "./config.js";
-import { type ChangeState } from "./git.js";
+import { type ChangeOptions, type ChangeState } from "./git.js";
 import { type AnalysisResult, type DecisionProvider } from "./provider.js";
 export interface TaskDecision {
     id: string;
@@ -28,10 +28,7 @@ export interface Plan {
 }
 export declare function createPlan(input: {
     config: Config;
-    cwd?: string;
-    base?: string;
-    head?: string;
     state?: ChangeState;
     provider?: DecisionProvider;
     cache?: boolean;
-}): Promise<Plan>;
+} & ChangeOptions): Promise<Plan>;

package/dist/planner.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { cacheDirectory } from "./cache.js";
 import { parseConfig, resolveApiKey, secretPatterns, } from "./config.js";
-import { collectChanges, git, matches } from "./git.js";
+import { collectChanges, 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();
@@ -60,7 +61,7 @@ export async function createPlan(input) {
         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 dir = await cacheDirectory(cwd);
                 const key = createHash("sha256")
                     .update(JSON.stringify({
                     version: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-affected",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Semantic task routing for software development, powered by Jev.",
   "type": "module",
   "license": "MIT",

package/skills/jev-affected/SKILL.md

@@ -13,12 +13,13 @@ projects and `npx jev-affected` elsewhere.
 1. Confirm the current directory is a Git repository and locate
    `jev-affected.yml`. Run `jev-affected init` only when setup is requested and no
    configuration exists.
-2. Ensure the relevant edits are committed. Version 0.1 compares commits and does
-   not include working-tree changes.
-3. On first use, or when privacy matters, run
-   `jev-affected inspect --base <ref>`. This previews the sanitized input locally
-   without sending a request.
-4. Run `jev-affected plan --json --base <ref>` and use its task decisions as the
+2. Choose the input mode. Use the default mode for committed branch changes,
+   `--working-tree --base <ref>` while editing, or `--staged` for the exact Git
+   index before a commit.
+3. On first use, or when privacy matters, run `jev-affected inspect` with the
+   same mode and base flags intended for planning. This previews the sanitized
+   input locally without sending a request.
+4. Run `jev-affected plan --json` with those same flags and use its task decisions as the
    record of what should run. Do not invent task reasons or commands.
 5. Run `jev-affected run --base <ref>` only when execution is requested. Commands
    come from the repository configuration and should be treated as repository
@@ -26,6 +27,10 @@ projects and `npx jev-affected` elsewhere.
 6. Report the selected and skipped task counts, actual model version, warnings,
    fallback decisions, and any failed task commands.
 
+Use `jev-affected cache status` to inspect the Git-local decision cache. Use
+`jev-affected cache clear` when a fresh semantic decision is needed; it removes
+only the cache directory resolved inside Git metadata.
+
 Use an explicit base ref in CI and shallow clones. Fetch enough history for Git to
 compute the merge base.