@diffci.com/diffci 0.1.0-alpha.3

package/dist-client/src/client/workflow-guard.js

@@ -0,0 +1,300 @@
+/**
+ * Can this installation change what the repository's CI does? (Phase 02, 2026-08-26.)
+ *
+ * The Phase 02 exit criterion is "seven days in a third-party repository, CI byte-identical". Two
+ * different things have to hold for that, and only one of them is about DiffCI's own code:
+ *
+ *   1. The observer must not touch the checkout. That is checked at run time, per run, by comparing
+ *      HEAD and `git status --porcelain` before and after (src/client/observe.ts).
+ *   2. The observer's JOB must not be able to influence any other job. That is a property of the
+ *      workflow file, not of DiffCI, and no amount of care inside the observer can establish it.
+ *
+ * This module is (2). It reads the repository's own workflow YAML and looks for the specific ways an
+ * added job stops being inert:
+ *
+ *   - Another job `needs:` it, so a DiffCI failure blocks real work.
+ *   - It is not `continue-on-error: true`, so a DiffCI failure becomes the WORKFLOW's conclusion - which
+ *     is what a required status check and a merge queue read. This is the one that surprises people:
+ *     the build jobs all pass, and the pull request is still red.
+ *   - It is not a dedicated job: DiffCI steps sit in a job that also builds or tests, where a slow
+ *     install or a mutated file is no longer isolated from anything.
+ *   - It can write. An observer with `contents: write` is one bug away from not being an observer.
+ *
+ * Findings are severity-ranked and carry stable codes. BLOCKING means the byte-identical claim cannot
+ * be made from this workflow, and the operator should fix the workflow before the seven days start -
+ * not that DiffCI failed.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import YAML from "yaml";
+/** Steps a dedicated observation job may legitimately contain besides the DiffCI action itself. */
+const ALLOWED_STEP_ACTIONS = [
+    "actions/checkout",
+    "actions/setup-node",
+    "actions/cache",
+    "actions/upload-artifact",
+];
+/** Permission scopes that make a job something other than a reader. `contents: read` is fine. */
+const WRITE_PERMISSION = "write";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asArray(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value === undefined || value === null)
+        return [];
+    return [value];
+}
+function permissionsGrantWrite(permissions) {
+    if (permissions === "write-all")
+        return ["write-all"];
+    if (!isRecord(permissions))
+        return [];
+    return Object.entries(permissions)
+        .filter(([, level]) => level === WRITE_PERMISSION)
+        .map(([scope]) => scope);
+}
+function listWorkflowFiles(repoPath) {
+    const dir = join(repoPath, ".github", "workflows");
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => name.endsWith(".yml") || name.endsWith(".yaml"))
+        .sort()
+        .map((name) => join(".github", "workflows", name));
+}
+/**
+ * `uses: owner/repo@ref` is pinned when `ref` is a full commit SHA. A tag or branch means the action's
+ * contents can change without the repository changing, which is exactly the property an installation
+ * promising byte-identical CI should not have.
+ */
+/**
+ * Does this step run DiffCI? Two forms have to be recognised, and only one of them has "diffci" in the
+ * string: a third-party repository writes `uses: owner/DiffCI.com@<sha>`, while this repository (and
+ * anyone vendoring the action) writes `uses: ./`, which names a directory. A guard that missed the
+ * local form would report "no job runs the DiffCI action" for the one installation we control - and
+ * silently check nothing.
+ */
+/**
+ * Does this step run DiffCI via a `run:` command rather than `uses:`?
+ *
+ * Since DiffCI became a proprietary package rather than a public Action, the generated workflow
+ * installs and invokes the agent with `run:` steps. A guard that only understood `uses:` reported
+ * "no job runs DiffCI" for the installation the product itself generates - and therefore checked
+ * nothing at all, while still returning a clean result. That is the worst possible failure for a
+ * safety check, so it is matched explicitly here.
+ */
+function runReferencesDiffCi(run, actionPattern) {
+    return actionPattern.test(commandText(run));
+}
+/**
+ * The part of a `run:` script that can invoke something: shell comments and URLs are removed line by
+ * line before matching. A URL is data handed to a command, not a command - DiffCI's own deploy
+ * workflow curls `https://diffci-research-sandbox.….workers.dev/…` and was reported as running the
+ * observer, then told its deploy job was a badly installed DiffCI job (2026-09-06). Everything the
+ * product generates keeps matching: `npm install … @diffci/observer@1.4.2`,
+ * `"${RUNNER_TEMP}/diffci/node_modules/.bin/diffci" observe`, `docker run … <image>@sha256:… observe`,
+ * `npx @diffci/observer observe` all name DiffCI outside any URL.
+ */
+function commandText(run) {
+    return run
+        .split("\n")
+        .map((line) => line.replace(/(^|\s)#.*$/, "$1").replace(/[a-z][a-z0-9+.-]*:\/\/\S+/gi, " "))
+        .join("\n");
+}
+/**
+ * Returns the offending specifier if a `run:` command installs DiffCI at anything other than an exact
+ * version or an image digest. This is the `run:`-shaped equivalent of the commit-SHA rule above: a
+ * customer who edits the generated "1.4.2" into "latest" has re-opened exactly the hole the generated
+ * workflow was written to close, and should be told so rather than getting a clean report.
+ */
+function findMutableAgentReference(run) {
+    for (const match of commandText(run).matchAll(/(@?[A-Za-z0-9._/-]*diffci[A-Za-z0-9._/-]*)@([^\s"']+)/gi)) {
+        const version = match[2];
+        if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version))
+            continue;
+        if (/^sha256:[0-9a-f]{64}$/.test(version))
+            continue;
+        return match[0];
+    }
+    return undefined;
+}
+function referencesDiffCi(uses, repoPath, actionPattern) {
+    if (actionPattern.test(uses))
+        return true;
+    if (!uses.startsWith("./"))
+        return false;
+    for (const file of ["action.yml", "action.yaml"]) {
+        const candidate = join(repoPath, uses.slice(2), file);
+        if (!existsSync(candidate))
+            continue;
+        try {
+            const parsed = YAML.parse(readFileSync(candidate, "utf8"));
+            if (isRecord(parsed) && typeof parsed.name === "string" && actionPattern.test(parsed.name))
+                return true;
+        }
+        catch {
+            // An unparseable local action is reported by the workflow scan itself, not silently trusted.
+        }
+    }
+    return false;
+}
+function isPinnedToSha(uses) {
+    const at = uses.lastIndexOf("@");
+    if (at === -1)
+        return uses.startsWith("./") || uses.startsWith("docker://");
+    return /^[0-9a-f]{40}$/i.test(uses.slice(at + 1));
+}
+export function auditWorkflows(repoPath, options = {}) {
+    const actionPattern = options.actionPattern ?? /diffci/i;
+    const findings = [];
+    const observerJobs = [];
+    const workflowsScanned = [];
+    for (const relativePath of listWorkflowFiles(repoPath)) {
+        let document;
+        try {
+            document = YAML.parse(readFileSync(join(repoPath, relativePath), "utf8"));
+        }
+        catch (error) {
+            findings.push({
+                severity: "WARNING",
+                code: "WORKFLOW_UNPARSEABLE",
+                message: `could not parse this workflow, so it was not checked: ${error.message.split("\n")[0]}`,
+                workflow: relativePath,
+            });
+            continue;
+        }
+        workflowsScanned.push(relativePath);
+        if (!isRecord(document))
+            continue;
+        const jobs = isRecord(document.jobs) ? document.jobs : {};
+        const workflowPermissions = permissionsGrantWrite(document.permissions);
+        for (const [jobId, rawJob] of Object.entries(jobs)) {
+            if (!isRecord(rawJob))
+                continue;
+            const steps = asArray(rawJob.steps).filter(isRecord);
+            const isDiffCiStep = (step) => (typeof step.uses === "string" && referencesDiffCi(step.uses, repoPath, actionPattern)) ||
+                (typeof step.run === "string" && runReferencesDiffCi(step.run, actionPattern));
+            const diffciSteps = steps.filter(isDiffCiStep);
+            if (diffciSteps.length === 0)
+                continue;
+            observerJobs.push(`${relativePath}#${jobId}`);
+            // 1. Nothing may depend on the observer.
+            const dependants = Object.entries(jobs)
+                .filter(([otherId, otherJob]) => otherId !== jobId && isRecord(otherJob) && asArray(otherJob.needs).includes(jobId))
+                .map(([otherId]) => otherId);
+            if (dependants.length > 0) {
+                findings.push({
+                    severity: "BLOCKING",
+                    code: "JOB_IS_A_DEPENDENCY",
+                    message: `job "${jobId}" is listed in needs: by ${dependants.join(", ")} - a DiffCI failure would block ${dependants.length === 1 ? "that job" : "those jobs"}. Remove the dependency.`,
+                    workflow: relativePath,
+                    job: jobId,
+                });
+            }
+            // 2. The observer's outcome must not become the workflow's outcome.
+            if (rawJob["continue-on-error"] !== true) {
+                findings.push({
+                    severity: "BLOCKING",
+                    code: "JOB_NOT_CONTINUE_ON_ERROR",
+                    message: `job "${jobId}" is missing continue-on-error: true - without it a DiffCI failure fails the whole workflow run, which a required status check or merge queue will read as a failed build.`,
+                    workflow: relativePath,
+                    job: jobId,
+                });
+            }
+            // 3. The observer must be alone in its job.
+            const foreignSteps = steps.filter((step) => {
+                // DiffCI's own steps are never foreign, whichever form they take. This has to come first: since
+                // DiffCI became a package rather than an Action it invokes itself with `run:`, and the rule
+                // below - "any run: step is real work" - was written when that could not happen. Leaving the
+                // order the other way round made the product's own generated workflow fail its own guard.
+                if (isDiffCiStep(step))
+                    return false;
+                // Any other shell step in this job IS real work, and DiffCI must not share a job with it.
+                if (typeof step.run === "string")
+                    return true;
+                if (typeof step.uses !== "string")
+                    return false;
+                return !ALLOWED_STEP_ACTIONS.some((allowed) => step.uses === allowed || step.uses.startsWith(`${allowed}@`));
+            });
+            if (foreignSteps.length > 0) {
+                findings.push({
+                    severity: "BLOCKING",
+                    code: "JOB_NOT_DEDICATED",
+                    message: `job "${jobId}" contains ${foreignSteps.length} step(s) that are not part of observation - DiffCI must run in a job of its own so it shares nothing with real work.`,
+                    workflow: relativePath,
+                    job: jobId,
+                });
+            }
+            // 4. An observer that can write is not an observer.
+            const jobPermissions = rawJob.permissions === undefined ? workflowPermissions : permissionsGrantWrite(rawJob.permissions);
+            if (jobPermissions.length > 0) {
+                findings.push({
+                    severity: "WARNING",
+                    code: "JOB_HAS_WRITE_PERMISSIONS",
+                    message: `job "${jobId}" ${rawJob.permissions === undefined ? "inherits" : "declares"} write permission for: ${jobPermissions.join(", ")}. Set permissions: { contents: read } on the job.`,
+                    workflow: relativePath,
+                    job: jobId,
+                });
+            }
+            // 5. A mutable reference means the code that runs here can change without this repository
+            // changing. Two forms have to be checked, because DiffCI is invoked both ways: a `uses:` step
+            // must name a commit SHA, and a `run:` step installing the agent must name an exact version.
+            // Checking only the first would let someone edit the generated "1.4.2" into "latest" and still
+            // get a clean report - which is the same hole, reopened by hand.
+            for (const step of diffciSteps) {
+                if (typeof step.uses === "string") {
+                    if (!isPinnedToSha(step.uses)) {
+                        findings.push({
+                            severity: "WARNING",
+                            code: "ACTION_NOT_PINNED",
+                            message: `"${step.uses}" is not pinned to a 40-character commit SHA, so what runs here can change without this repository changing.`,
+                            workflow: relativePath,
+                            job: jobId,
+                        });
+                    }
+                    continue;
+                }
+                if (typeof step.run === "string") {
+                    const mutable = findMutableAgentReference(step.run);
+                    if (mutable) {
+                        findings.push({
+                            severity: "WARNING",
+                            code: "AGENT_NOT_PINNED",
+                            message: `"${mutable}" is not an exact version, so the DiffCI agent running here can change without this repository changing.`,
+                            workflow: relativePath,
+                            job: jobId,
+                        });
+                    }
+                }
+            }
+            // 6. A shared concurrency group lets this job cancel another one.
+            const group = isRecord(rawJob.concurrency) ? rawJob.concurrency.group : rawJob.concurrency;
+            if (typeof group === "string") {
+                const sharing = Object.entries(jobs)
+                    .filter(([otherId, otherJob]) => {
+                    if (otherId === jobId || !isRecord(otherJob))
+                        return false;
+                    const otherGroup = isRecord(otherJob.concurrency) ? otherJob.concurrency.group : otherJob.concurrency;
+                    return otherGroup === group;
+                })
+                    .map(([otherId]) => otherId);
+                if (sharing.length > 0) {
+                    findings.push({
+                        severity: "WARNING",
+                        code: "JOB_SHARES_CONCURRENCY_GROUP",
+                        message: `job "${jobId}" shares concurrency group "${group}" with ${sharing.join(", ")}, so one can cancel the other.`,
+                        workflow: relativePath,
+                        job: jobId,
+                    });
+                }
+            }
+        }
+    }
+    return { observerJobs, findings, workflowsScanned };
+}
+/** True when nothing found would let the observation change what the rest of CI does. */
+export function isNonInterfering(result) {
+    return result.findings.every((finding) => finding.severity !== "BLOCKING");
+}

package/dist-client/src/git/git-diff.js

@@ -0,0 +1,379 @@
+import { spawnSync } from "node:child_process";
+import { dirname } from "node:path";
+export const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+export const ZERO_SHA = "0000000000000000000000000000000000000000";
+function runGit(args, repoPath) {
+    const result = spawnSync("git", args, {
+        cwd: repoPath,
+        encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    return {
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        status: result.status,
+    };
+}
+function runGitOrThrow(args, repoPath, context) {
+    const result = runGit(args, repoPath);
+    if (result.status !== 0) {
+        const message = result.stderr.trim() || result.stdout.trim() || "unknown error";
+        throw new GitDiffError(`${context} failed: ${message}`, {
+            command: `git ${args.join(" ")}`,
+            stderr: result.stderr,
+            exitCode: result.status ?? undefined,
+        });
+    }
+    return result.stdout;
+}
+class GitDiffError extends Error {
+    details;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = "GitDiffError";
+        this.details = details;
+    }
+}
+const STATUS_TO_CHANGE_TYPE = {
+    A: "added",
+    C: "copied",
+    D: "deleted",
+    M: "modified",
+    R: "renamed",
+    T: "modified",
+    U: "unmerged",
+    X: "unknown",
+    B: "unknown",
+};
+function mapStatusCode(code) {
+    const first = code.charAt(0);
+    return STATUS_TO_CHANGE_TYPE[first] ?? "unknown";
+}
+export function parseNameStatus(buffer) {
+    const text = buffer.toString("utf8");
+    const tokens = text.split("\0");
+    const files = [];
+    let i = 0;
+    while (i < tokens.length) {
+        const statusToken = tokens[i];
+        if (!statusToken) {
+            i += 1;
+            continue;
+        }
+        const code = statusToken.charAt(0);
+        const similarity = statusToken.length > 1 ? parseInt(statusToken.slice(1), 10) : undefined;
+        i += 1;
+        if (i >= tokens.length) {
+            break;
+        }
+        const firstPath = tokens[i];
+        i += 1;
+        if (code === "R" || code === "C") {
+            if (i >= tokens.length) {
+                break;
+            }
+            const secondPath = tokens[i];
+            i += 1;
+            files.push({
+                path: secondPath,
+                oldPath: firstPath,
+                changeType: mapStatusCode(code),
+                similarityScore: Number.isFinite(similarity) ? similarity : undefined,
+            });
+        }
+        else {
+            files.push({
+                path: firstPath,
+                changeType: mapStatusCode(code),
+            });
+        }
+    }
+    return files;
+}
+function parseNumstatRecord(record) {
+    if (!record)
+        return undefined;
+    const fields = record.split("\t");
+    if (fields.length < 3)
+        return undefined;
+    const isBinary = fields[0]?.trimStart().startsWith("-") ?? false;
+    const hasRename = fields.length >= 4;
+    const newPath = hasRename ? fields[fields.length - 1] : fields[2];
+    if (!newPath)
+        return undefined;
+    return { path: newPath, isBinary };
+}
+export function parseNumstat(buffer) {
+    const text = buffer.toString("utf8");
+    const records = text.split("\0");
+    const binaryByNewPath = new Map();
+    for (const record of records) {
+        const parsed = parseNumstatRecord(record);
+        if (parsed) {
+            binaryByNewPath.set(parsed.path, parsed.isBinary);
+        }
+    }
+    return binaryByNewPath;
+}
+export function normalizeDirectories(paths) {
+    const seen = new Set();
+    const dirs = [];
+    for (const filePath of paths) {
+        if (!filePath)
+            continue;
+        const dir = dirname(filePath);
+        if (dir === ".")
+            continue;
+        if (!seen.has(dir)) {
+            seen.add(dir);
+            dirs.push(dir);
+        }
+    }
+    dirs.sort((a, b) => a.localeCompare(b));
+    return dirs;
+}
+const CONFIG_PATTERNS = [
+    /^next\.config\./,
+    /^tsconfig\.json$/,
+    /^jsconfig\.json$/,
+    /^eslint\.config\./,
+    /^eslint\.rc/,
+    /^\.eslint/,
+    /^postcss\.config\./,
+    /^tailwind\.config\./,
+    /^\.prettier/,
+    /^prettier\.config\./,
+    /^vitest\.config\./,
+    /^jest\.config\./,
+    /^playwright\.config\./,
+    /^webpack\.config\./,
+    /^rollup\.config\./,
+    /^esbuild\.config\./,
+    /^\.github\//,
+    /^\.docker/,
+    /^Dockerfile/,
+    /^docker-compose/,
+    /^ops\//,
+    /^database\//,
+    /^package\.json$/,
+    /^package-lock\.json$/,
+    /^yarn\.lock$/,
+    /^pnpm-lock\.yaml$/,
+    /^bun\.lockb$/,
+    /^(npm|pnpm|yarn)-lock\./,
+];
+// Stage 1B fix (2026-08-21, docs/research/2026-08-21-stage1b-*.md): root-caused in Stage 1A's fallback-
+// composition analysis - dependencyManifestChanged previously fired on ANY change to the root
+// package.json, including fields with zero behavioral effect (description, keywords, author, homepage,
+// license, contributors, bugs, repository). Only these fields can actually change what gets built/
+// tested/resolved; everything else is metadata a change to which should never force FULL fallback.
+const PACKAGE_JSON_RELEVANT_FIELDS = [
+    "dependencies", "devDependencies", "peerDependencies", "optionalDependencies",
+    "scripts", "exports", "main", "module", "type", "bin", "engines", "workspaces", "browser",
+];
+/** Narrows a path-based "package.json changed" signal to whether any behaviorally-relevant field
+ * actually changed, given both versions' raw content. Returns true (never narrows) whenever either
+ * side is missing/unparseable - a file that was added, deleted, or became invalid JSON is unambiguously
+ * not a case for field-level narrowing, and an unparseable "before" or "after" state means there is
+ * nothing safe to compare. This function only ever narrows true -> false, never invents a change that
+ * a path-based check didn't already flag. */
+export function hasRelevantPackageJsonChange(oldContent, newContent) {
+    if (oldContent === undefined || newContent === undefined)
+        return true;
+    let oldJson;
+    let newJson;
+    try {
+        oldJson = JSON.parse(oldContent);
+        newJson = JSON.parse(newContent);
+    }
+    catch {
+        return true;
+    }
+    return PACKAGE_JSON_RELEVANT_FIELDS.some((field) => JSON.stringify(oldJson[field]) !== JSON.stringify(newJson[field]));
+}
+/** Reads a file's content at a specific commit via `git show <sha>:<path>`, without touching the
+ * working tree (safe to call regardless of what's currently checked out). Returns undefined - not an
+ * error - when the file doesn't exist at that commit (a newly-added or since-deleted file), which is
+ * the expected, common case this is called for, not an exceptional one. */
+function readFileAtSha(sha, path, repoPath) {
+    const result = runGit(["show", `${sha}:${path}`], repoPath);
+    if (result.status !== 0)
+        return undefined;
+    return result.stdout;
+}
+export function computeAnalysis(files) {
+    const paths = files.flatMap((f) => f.oldPath ? [f.path, f.oldPath] : [f.path]);
+    const matches = (pattern) => paths.some((p) => pattern.test(p));
+    return {
+        empty: files.length === 0,
+        configChanged: CONFIG_PATTERNS.some(matches),
+        dependencyManifestChanged: matches(/^package\.json$/),
+        lockfileChanged: matches(/^package-lock\.json$/) ||
+            matches(/^yarn\.lock$/) ||
+            matches(/^pnpm-lock\.yaml$/) ||
+            matches(/^bun\.lockb$/),
+        workflowChanged: matches(/^\.github\/workflows\//),
+        infrastructureChanged: matches(/^ops\//),
+        databaseChanged: matches(/^database\//),
+    };
+}
+export function summarize(files) {
+    const s = {
+        added: 0,
+        modified: 0,
+        deleted: 0,
+        renamed: 0,
+        copied: 0,
+        unmerged: 0,
+        unknown: 0,
+        total: files.length,
+    };
+    for (const file of files) {
+        switch (file.changeType) {
+            case "added":
+                s.added += 1;
+                break;
+            case "modified":
+                s.modified += 1;
+                break;
+            case "deleted":
+                s.deleted += 1;
+                break;
+            case "renamed":
+                s.renamed += 1;
+                break;
+            case "copied":
+                s.copied += 1;
+                break;
+            case "unmerged":
+                s.unmerged += 1;
+                break;
+            default:
+                s.unknown += 1;
+                break;
+        }
+    }
+    return s;
+}
+export function resolveCommitParents(sha, repoPath) {
+    const output = runGitOrThrow(["rev-list", "--parents", "-n", "1", sha], repoPath, "Resolve commit parents").trim();
+    const parts = output.split(/\s+/);
+    return parts.slice(1); // first token is the commit itself
+}
+function validateCommits(baseSha, headSha, repoPath) {
+    for (const sha of [baseSha, headSha]) {
+        if (!sha || sha === ZERO_SHA || (!/^[0-9a-f]{4,40}$/i.test(sha) && !/^[A-Za-z0-9/_.^~@-]+$/i.test(sha))) {
+            throw new GitDiffError(`Invalid commit SHA: ${sha}`);
+        }
+    }
+    for (const sha of [baseSha, headSha]) {
+        if (sha === EMPTY_TREE_SHA)
+            continue;
+        runGitOrThrow(["cat-file", "-t", `${sha}^{commit}`], repoPath, "SHA validation");
+    }
+}
+function headHasParent(headSha, repoPath) {
+    const parents = resolveCommitParents(headSha, repoPath);
+    return parents.length > 0;
+}
+/**
+ * Canonical HEAD file inventory (see RepositoryInventory). One `git ls-tree` per analysis - cheap
+ * (~tens of ms for ~10k paths) and already co-located with the only code that knows repoPath+headSha.
+ * Failure is NOT fatal: returns undefined so the delta analysis still succeeds and relationship-based
+ * classification simply stays inert (conservative: affected files remain "unknown" -> fallback).
+ */
+export function readRepositoryInventory(headSha, repoPath) {
+    const result = runGit(["ls-tree", "-r", "--name-only", "-z", headSha], repoPath);
+    if (result.status !== 0)
+        return undefined;
+    const files = new Set(result.stdout.split("\0").filter((p) => p.length > 0));
+    if (files.size === 0)
+        return undefined; // an empty listing is never a trustworthy inventory
+    return { headSha, files, source: "git-ls-tree" };
+}
+export async function analyzeGitDelta(options = {}) {
+    const repoPath = options.repoPath;
+    try {
+        const headSha = options.headSha ??
+            runGitOrThrow(["rev-parse", "HEAD"], repoPath, "Resolve HEAD").trim();
+        let baseSha = options.baseSha;
+        if (!baseSha) {
+            baseSha = headHasParent(headSha, repoPath)
+                ? runGitOrThrow(["rev-parse", `${headSha}^`], repoPath, "Resolve base").trim()
+                : EMPTY_TREE_SHA;
+        }
+        validateCommits(baseSha, headSha, repoPath);
+        const findRenamesArg = options.findRenames
+            ? `--find-renames=${typeof options.findRenames === "string" ? options.findRenames : "50%"}`
+            : "--find-renames=50%";
+        const nameStatus = runGitOrThrow([
+            "diff-tree",
+            "-r",
+            "--name-status",
+            "-z",
+            findRenamesArg,
+            baseSha,
+            headSha,
+        ], repoPath, "Resolve changed files");
+        const files = parseNameStatus(Buffer.from(nameStatus, "utf8"));
+        const numstat = runGitOrThrow(["diff-tree", "-r", "--numstat", "-z", findRenamesArg, baseSha, headSha], repoPath, "Resolve binary metadata");
+        const binaryMap = parseNumstat(Buffer.from(numstat, "utf8"));
+        const filesWithBinary = files.map((file) => ({
+            ...file,
+            isBinary: binaryMap.get(file.path),
+        }));
+        const allPaths = filesWithBinary.flatMap((f) => f.oldPath ? [f.path, f.oldPath] : [f.path]);
+        const analysis = computeAnalysis(filesWithBinary);
+        // Stage 1B fix (2026-08-21): narrow the path-based dependencyManifestChanged signal to whether a
+        // behaviorally-relevant field actually changed - only attempted when the root package.json itself
+        // was modified (not added/deleted/renamed, which stay unambiguously true - see
+        // hasRelevantPackageJsonChange()'s own doc comment) and only ever narrows true -> false.
+        if (analysis.dependencyManifestChanged) {
+            const changedPackageJson = filesWithBinary.find((f) => f.path === "package.json" && f.changeType === "modified");
+            if (changedPackageJson) {
+                const oldContent = readFileAtSha(baseSha, "package.json", repoPath);
+                const newContent = readFileAtSha(headSha, "package.json", repoPath);
+                analysis.dependencyManifestChanged = hasRelevantPackageJsonChange(oldContent, newContent);
+            }
+        }
+        const delta = {
+            baseSha,
+            headSha,
+            files: filesWithBinary,
+            directories: normalizeDirectories(allPaths),
+            summary: summarize(filesWithBinary),
+            analysis,
+        };
+        return { success: true, delta, inventory: readRepositoryInventory(headSha, repoPath) };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: message,
+        };
+    }
+}
+export function gitDeltaToJson(delta) {
+    return JSON.stringify(delta, (_key, value) => (typeof value === "bigint" ? value.toString() : value), 2);
+}
+export { GitDiffError };
+export function isAllZeroSha(sha) {
+    return typeof sha === "string" && /^0+$/.test(sha);
+}
+export function findRecentNonEmptyCommitPair(repoPath, maxWalk = 32) {
+    const head = runGitOrThrow(["rev-parse", "HEAD"], repoPath, "Resolve HEAD").trim();
+    const candidates = runGitOrThrow(["rev-list", "--first-parent", "-n", String(maxWalk + 1), head], repoPath, "List first-parent commits").trim().split("\n");
+    for (let i = 0; i < candidates.length - 1; i++) {
+        const headSha = candidates[i];
+        const baseSha = candidates[i + 1];
+        const diffFiles = runGit(["diff-tree", "--no-commit-id", "--name-only", "-r", baseSha, headSha], repoPath);
+        if (diffFiles.status === 0 && diffFiles.stdout.trim().length > 0) {
+            return { baseSha, headSha, emptyBase: false, firstParent: true };
+        }
+    }
+    if (candidates.length > 0) {
+        return { baseSha: EMPTY_TREE_SHA, headSha: candidates[0], emptyBase: true, firstParent: true };
+    }
+    return undefined;
+}

package/dist-client/src/git/types.js

@@ -0,0 +1 @@
+export {};