@deftai/directive-core 0.107.0 → 0.109.0

package/dist/orphan-active/candidate-scope.js

@@ -0,0 +1,157 @@
+/**
+ * Candidate diff ownership for the merge-chokepoint orphan run (#3893).
+ *
+ * The unscoped sweep enumerates every running brief under `active/`. Composed
+ * on `check:merge` that gives one stranded brief merge authority over every
+ * open PR, and N stranded briefs make N single-brief lifecycle PRs mutually
+ * unmergeable — each leaves the other orphan. The pre-merge run cannot see the
+ * residue its own candidate is about to create either: that candidate's linked
+ * PR still reads `merged_at: null` while the gate runs.
+ *
+ * Scoping the merge run to the candidate's own diff removes the coupling
+ * without touching the detector. Repo-wide truth stays enforced at the
+ * delivery tip (HEAD on the delivery line falls back to the full sweep) and
+ * after merge (`--issue N`, #3429).
+ */
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { resolveDeliveryBranch } from "../policy/delivery-branch.js";
+import { defaultGitRunner } from "../session/git.js";
+/** Symlink-resolved path, or the input when it cannot be resolved. */
+function realpathOrSelf(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return path;
+        }
+    }
+}
+/**
+ * Canonical directory: symlinks resolved, then precomposed. Git reports the
+ * canonical worktree root while the lifecycle root keeps the caller's
+ * spelling, and git precomposes Unicode (`core.precomposeunicode`) while some
+ * filesystems hand `readdir` the decomposed form.
+ */
+function canonicalDir(path) {
+    return realpathOrSelf(resolve(path)).normalize("NFC");
+}
+/**
+ * One comparable form for a git path and a readdir path.
+ *
+ * Only the directory is canonicalized: the file itself may be a deletion in
+ * the candidate diff and no longer exist on disk.
+ */
+export function normalizeScopePath(path) {
+    const abs = resolve(path);
+    const full = join(canonicalDir(dirname(abs)), basename(abs)).normalize("NFC");
+    return process.platform === "win32" ? full.toLowerCase() : full;
+}
+function sweep(reason) {
+    return { kind: "sweep", reason };
+}
+/**
+ * Split `-z` git output. NUL-delimited paths are never C-quoted, so a brief
+ * whose name git would quote (non-ASCII, quotes, backslashes) still compares
+ * equal to the readdir path instead of silently falling outside the candidate
+ * scope. `GitRunner` returns `-z` output as latin1 bytes, so decode to UTF-8.
+ */
+function splitNulPaths(stdout) {
+    return stdout
+        .split("\0")
+        .map((entry) => Buffer.from(entry, "latin1").toString("utf8"))
+        .filter((entry) => entry.length > 0);
+}
+function refExists(cwd, ref, runGit) {
+    return runGit(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]).code === 0;
+}
+/**
+ * Base ref for the candidate diff: explicit override, else `origin/<branch>`,
+ * else the local delivery branch. Null when none resolves.
+ */
+export function resolveCandidateBaseRef(projectRoot, override, runGit) {
+    const explicit = override?.trim() ?? "";
+    if (explicit.length > 0) {
+        return refExists(projectRoot, explicit, runGit) ? explicit : null;
+    }
+    const branch = resolveDeliveryBranch(projectRoot, runGit).branch;
+    for (const candidate of [`origin/${branch}`, branch]) {
+        if (refExists(projectRoot, candidate, runGit)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Brief paths under `activeDir` that the candidate's own diff touches.
+ *
+ * Falls back to the repo-wide sweep — never to a narrower scan — when git,
+ * the base ref, or the diff is unavailable, so the flag cannot silently
+ * shrink what a merge gate looks at.
+ */
+export function resolveCandidateScope(projectRoot, activeDir, options = {}) {
+    const runGit = options.runGit ?? defaultGitRunner;
+    const root = resolve(projectRoot);
+    const topLevel = runGit(root, ["rev-parse", "--show-toplevel"]);
+    if (topLevel.code !== 0) {
+        return sweep("not a git worktree, so no candidate diff exists");
+    }
+    const gitRoot = topLevel.stdout.trim();
+    if (gitRoot.length === 0) {
+        return sweep("git worktree root could not be resolved");
+    }
+    const baseRef = resolveCandidateBaseRef(root, options.baseRef, runGit);
+    if (baseRef === null) {
+        const requested = options.baseRef?.trim() ?? "";
+        return sweep(requested.length > 0
+            ? `base ref '${requested}' not found; fetch it or pass a resolvable --base-ref`
+            : "no delivery base ref found (no origin/<deliveryBranch> or local branch); fetch it or pass --base-ref");
+    }
+    // HEAD at or behind the delivery line is the delivery tip itself, not a
+    // candidate: keep repo-wide truth there.
+    if (runGit(root, ["merge-base", "--is-ancestor", "HEAD", baseRef]).code === 0) {
+        return sweep(`HEAD is on the ${baseRef} delivery line, so this run is the delivery-tip check`);
+    }
+    const mergeBase = runGit(root, ["merge-base", "HEAD", baseRef]);
+    if (mergeBase.code !== 0) {
+        return sweep(`could not compute the merge base with ${baseRef}`);
+    }
+    const base = mergeBase.stdout.trim();
+    if (base.length === 0) {
+        return sweep(`merge base with ${baseRef} is empty`);
+    }
+    // Canonicalize both sides before the relative: a symlinked checkout or an
+    // unequal Unicode spelling of the same root would otherwise read as `..`
+    // and restore the repo-wide sweep.
+    const activeRel = relative(canonicalDir(gitRoot), canonicalDir(activeDir)).replace(/\\/g, "/");
+    if (activeRel.length === 0 || activeRel.startsWith("..")) {
+        return sweep("active/ is outside the git worktree");
+    }
+    // Diff against the working tree, not HEAD: a locally activated brief is a
+    // pre-commit `task check` candidate too.
+    const changed = runGit(gitRoot, ["diff", "--name-only", "-z", base, "--", activeRel]);
+    if (changed.code !== 0) {
+        return sweep(`could not diff active/ against ${baseRef}`);
+    }
+    const untracked = runGit(gitRoot, [
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "-z",
+        "--",
+        activeRel,
+    ]);
+    if (untracked.code !== 0) {
+        return sweep("could not list untracked briefs under active/");
+    }
+    const paths = new Set();
+    for (const rel of [...splitNulPaths(changed.stdout), ...splitNulPaths(untracked.stdout)]) {
+        paths.add(normalizeScopePath(resolve(gitRoot, rel)));
+    }
+    return { kind: "diff", baseRef, paths };
+}
+//# sourceMappingURL=candidate-scope.js.map

package/dist/orphan-active/evaluate.d.ts

@@ -1,4 +1,5 @@
 import type { RunGhFn } from "../pr-protected-issues/types.js";
+import type { GitRunner } from "../session/git.js";
 export type OutputStream = "stdout" | "stderr" | "none";
 export type OrphanKind = "shipped" | "unresolved";
 export interface OrphanActiveBrief {
@@ -6,11 +7,40 @@ export interface OrphanActiveBrief {
     readonly reason: string;
     readonly kind: OrphanKind;
 }
+/**
+ * How the run's issue-state verdicts were reached (#3767). A pass with
+ * `unverified > 0` is not evidence that the tree is clean.
+ */
+export interface OrphanActiveBasis {
+    readonly inventory: number;
+    readonly live: number;
+    readonly cache: number;
+    readonly unverified: number;
+    /** Oldest cache entry that produced a verdict, in ms. */
+    readonly maxCacheAgeMs: number | null;
+    /** True when reads resolved through `ghx`, a cached GET proxy. */
+    readonly proxied: boolean;
+    readonly elapsedMs: number;
+    readonly budgetMs: number;
+}
+/** What merge-chokepoint scoping decided for this run (#3893). */
+export interface OrphanActiveScopeSummary {
+    readonly kind: "diff" | "sweep";
+    /** Ref the candidate diff was taken against; null on a sweep. */
+    readonly baseRef: string | null;
+    /** Why the run stayed repo-wide; null on a candidate diff. */
+    readonly reason: string | null;
+    /** Running briefs left unevaluated because this candidate does not own them. */
+    readonly skipped: number;
+}
 export interface EvaluateResult {
     readonly code: 0 | 1 | 2;
     readonly message: string;
     readonly stream: OutputStream;
     readonly orphans: readonly OrphanActiveBrief[];
+    readonly basis: OrphanActiveBasis;
+    /** Null unless `changedOnly` was requested. */
+    readonly scope: OrphanActiveScopeSummary | null;
 }
 export interface EvaluateOptions {
     readonly quiet?: boolean;
@@ -19,6 +49,17 @@ export interface EvaluateOptions {
     readonly skipGh?: boolean;
     /** When set, scan only active/running briefs that reference this issue (#3429). */
     readonly issue?: number | null;
+    /** Monotonic clock seam so basis ages and budget checks are testable. */
+    readonly nowMs?: () => number;
+    /**
+     * Merge-chokepoint scoping (#3893): evaluate only active/running briefs the
+     * candidate's own diff touches. Ignored with `issue`, which is already one
+     * origin. Falls back to the repo-wide sweep when the base ref is unresolvable.
+     */
+    readonly changedOnly?: boolean;
+    /** Base ref for `changedOnly`; defaults to `origin/<deliveryBranch>`. */
+    readonly baseRef?: string | null;
+    readonly runGit?: GitRunner;
 }
 /**
  * Pure evaluator for orphaned active/running xBRIEF detection (#2321 / #3429).
@@ -26,6 +67,17 @@ export interface EvaluateOptions {
  * issues and/or a merged PR — the stop-at:pr-open orphan signature.
  * Pass `issue` to scan one origin after merge. Confirmed shipped prints
  * scope:complete; unresolved lookup still exits 1 with a retry remediation.
+ *
+ * Issue state resolves by query shape (#3767): scoped `--issue N` takes an
+ * authoritative read and stays fail-closed on unknown; the unscoped sweep uses
+ * one complete, fail-closed open-issue inventory and stays fail-open on
+ * unknown so offline work is not network-authorized. A cache hit is honoured
+ * only inside `ISSUE_CACHE_MAX_AGE_MS`, and every verdict reports its basis.
+ *
+ * `changedOnly` is the merge-chokepoint form (#3893): only briefs the
+ * candidate's own diff touches are evaluated, so a brief stranded by another
+ * merge cannot fail this candidate. It falls back to the repo-wide sweep at
+ * the delivery tip and whenever the base ref is unresolvable.
  */
 export declare function evaluate(projectRoot: string, options?: EvaluateOptions): EvaluateResult;
 //# sourceMappingURL=evaluate.d.ts.map